HTTP Status Codes for RESTful APIs

HTTP status codes are the response codes supplied by the web servers against any HTTP request. These codes are 3-digit integer values where the first digit of the code specifies one of five classes of response. There are different series of HTTP status codes. Each status code series have their own status category and each status code has a specific meaning.

1xx = Informational – It means the request has been received and the process is continuing.
2xx = Success – It means the action was successfully received, understood, and accepted.
3xx = Redirection – It means further action must be taken in order to complete the request.
4xx = Client Error – It means the request contains incorrect syntax or cannot be fulfilled.
5xx = Server Error – It means the server failed to fulfill an apparently valid request.

All the HTTP status codes are a part of the HTTP/1.1 standard. The Internet Assigned Numbers Authority (IANA) maintains the official registry of the HTTP status codes.

The most useful HTTP status codes

I’ll only discuss the most common HTTP status codes here which we generally require during our regular development process. Here is the detailed description of the HTTP status codes below.

100 – Continue – This means the server has received the initial part of the request i.e. the request headers. This intermediate response is used to inform the client that the request has not yet been rejected by the server and the client should proceed sending the rest of the request i.e. the request body or, if the request has already been completed, ignore this response. This helps in case of very large requests where clients can determine the connection sending only the request headers. The server must send a final response after the request has been completed.

Other 1xx response codes are rare and we do not need to deal with these codes many times in the regular development process.

101 – The server is switching the protocols.
102 – The server is processing the request.

2xx – Success:

200 – OK – Known as the “200 OK” success code. This is the standard response code for a successful HTTP request. The response is sometimes dependent on the HTTP request method, i.e. GET, POST, HEAD, PUT, TRACE, DELETE, etc.

Other 2xx response codes are rare and we do not need to deal with these codes many times in the regular development process.

201 – Created
202 – Accepted
203 – Non-Authoritative Information
204 – No content
205 – Reset content
206 – Partial content.

3xx – Redirection:

301 – Moved Permanently – The requested resource has been moved permanently and assigned with a new permanent URI. Any future references to this resource should be requested with the new URI. This response is cacheable unless indicated otherwise with the request.

302 – Found – The requested resource has been moved temporarily under a different URI. Since the URI might be changed again, the client should continue to use the requested URI for future requests as well. Now, the HTTP/1.0 specification required the client to perform a temporary redirect, referred to as “Moved Temporarily”, but the popular browsers implemented 302 with the additional response code of a 303 See Other. Then, HTTP/1.1 added status codes 303 and 307 to identify the two different behaviors.

304 – Not Modified – This code means the resource has not been modified since it was requested the last time. The HTTP client provides a header to supply a time against which to compare. Using this saves bandwidth and reprocessing on both the server and client, as only the header data must be sent and received.

Other 3xx response codes are rare and we do not need to deal with these codes many times in the regular development process.

300 – Multiple Choices
303 – See Other
305 – Use Proxy
307 – Temporary Redirect
308 – Permanent Redirect

4xx – Client Error:

400 – Bad Request – The server did not understand the request or the request cannot be fulfilled, maybe due to malformed data or syntax. The client should modify the request first before making further requests with the same syntax or data.

401 – Unauthorized – This means the requested URL needs an authentication through a WWW-Authentication header, known as basic HTTP authentication. So the client should either include an HTTP authentication header within the request or if the authentication header is already included then the credentials might not be correct.

403 – Forbidden – The server is refusing to fulfill the request. It doesn’t mean that the request is not valid. Unlikely 401, the authorization will not help and the request should not be repeated.

404 – Not Found – The requested resource could not be found on the server currently but may be available again in the future. If the situation is permanent and known then 410 Gone status code should be used instead.

405 – Method Not Allowed – The method specified in the request is not allowed by the server. This status code is helpful to reject API calls with invalid request methods.

408 – Request Timeout – The server was timed out waiting for the request. The request was not produced by the client within the time frame the server was prepared to wait for.

410 – Gone – This means that the resource requested is no longer available and will not be available again. This status code should be used when a resource has been removed intentionally to purge it. This code is very helpful to indicate search engines to remove an indexed URI.

413 – Payload Too Large – The request is too large than the server can interpret or process. This status code can be used to prevent huge POST requests.

414 – Request-URI Too Long – The requested URI is too long for the server to process. This status code is used to prevent requests with lots of GET parameters with it which makes it too long.

429 – Too Many Requests – The client has sent too many requests within a given frame of time. This status code is intended for use with rate-limiting APIs.

Other 4xx response codes are rare and we do not need to deal with these codes many times in the regular development process.

402 – Payment Required
406 – Not Acceptable
407 – Proxy Authentication Required
409 – Conflict
411 – Length Required
412 – Precondition Failed
415 – Unsupported Media Type
416 – Range Not Satisfiable
417 – Expectation Failed
421 – Misdirected Request
422 – Unprocessable Entity
423 – Locked
424 – Failed Dependency
426 – Upgrade Required
428 – Precondition Required
431 – Request Header Fields Too Large
451 – Unavailable For Legal Reasons

5xx – Server Error:

500 – Internal Server Error – The request was not completed. The server encountered an unexpected exception which prevented it from fulfilling the request.

501 – Not Implemented – The server either does not recognize the request method or does not support the functionality required to complete the request. This is the appropriate response when the server does not recognize the request method and is not capable of supporting it.

502 – Bad Gateway – The server was acting as a gateway or proxy and received an invalid response from the upstream server it accessed while attempting to fulfill the request.

503 – Service Unavailable – The server is either temporarily overloaded or down for maintenance, hence currently not able to handle the request. This indicates a temporary state which may get altered at a later time.

504 – Gateway Timeout – The server was acting as a gateway or proxy (e.g. using Nginx proxy server) and did not receive a response back from the upstream server in a timely manner.

Other 5xx response codes are rare and we do not need to deal with these codes many times in the regular development process.

505 – HTTP Version Not Supported
506 – Variant Also Negotiates
507 – Insufficient Storage
508 – Loop Detected
509 – Unassigned
510 – Not Extended
511 – Network Authentication Required