Search code examples
httphttp-status-codes

HTTP status code 4xx vs 5xx

I am creating a REST API and find it difficult to choose the right HTTP status code to return in some cases.

Let's say I expect a certain value, and when it is not present I cannot perform a certain task and return an error. Because of the missing value the server cannot handle the request, but it was the client who sent it, wellformed but incomplete, in. Would it be best to return a 4xx or a 5xx error?

Solution

  • Stick to the standards!

    The decision of which HTTP status code you will send to the client is up to you but you really should stick to the standards. The RFC 7231 is the current reference for content and semantics of the HTTP/1.1 protocol. It's a must read when creating an API on the top of the HTTP protocol.

    4xx vs 5xx status codes

    Use 4xx status codes for client errors and 5xx status codes for server errors:

    6.5. Client Error 4xx

    The 4xx (Client Error) class of status code indicates that the client seems to have erred. Except when responding to a HEAD request, the server SHOULD send a representation containing an explanation of the error situation, and whether it is a temporary or permanent condition. These status codes are applicable to any request method. User agents SHOULD display any included representation to the user.

    6.6. Server Error 5xx

    The 5xx (Server Error) class of status code indicates that the server is aware that it has erred or is incapable of performing the requested method. Except when responding to a HEAD request, the server SHOULD send a representation containing an explanation of the error situation, and whether it is a temporary or permanent condition. A user agent SHOULD display any included representation to the user. These response codes are applicable to any request method.

    Which status code you should use

    For the situation you mentioned in your question, you could use 400 or maybe 422 (from WebDAV, a HTTP extension):

    6.5.1. 400 Bad Request

    The 400 (Bad Request) status code indicates that the server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).

    11.2. 422 Unprocessable Entity

    The 422 (Unprocessable Entity) status code means the server understands the content type of the request entity (hence a 415(Unsupported Media Type) status code is inappropriate), and the syntax of the request entity is correct (thus a 400 (Bad Request) status code is inappropriate) but was unable to process the contained instructions. For example, this error condition may occur if an XML request body contains well-formed (i.e., syntactically correct), but semantically erroneous, XML instructions.

    Along with the status code, ensure you send a representation (such as JSON or XML) containing an explanation of the error situation in the response payload. Have a look at the RFC 7807, it describes a stardard for problem details for HTTP APIs.

    A great decision chart

    For more details, check this decision chart from Racksburg:


    The status codes are grouped into three rough categories:

    HTTP status codes categories


    Start here:

    HTTP status codes


    Choosing 2xx and 3xx status codes:

    HTTP 2xx and 3xx status codes


    Choosing 4xx status codes:

    HTTP 4xx status codes


    Choosing 5xx status codes:

    HTTP 5xx status codes