API Status Codes

a few months ago

Whenever a system sends a request to the Server or the Backend, they in return provide with   a response and tell them what is the result of their Client Request. Depending on that responses then the Client Application takes further steps.

These responses are the Hypertext Transfer Protocol(HTTP) status codes. Status codes are issued by the server as a reply to the client’s request. The codes help in determining whether a HTTP request was successfully completed or not that was submitted by an application. These codes are having information from the IETF Request for Comments (RFC), and some additional codes that are useful in getting different information about the current status of the HTTP request.

HTTP status codes are 3-digit code, in which the first digit explains about the five standards classes of the responses. These responses have generic definition that is same for everyone working with the HTTP Request but the end user will be seeing some readable information that is understood by them.

All the HTTPS status codes are divided into the Five different categories or can be defined as Five Classes. The bifurcation helps in the easy distribution of different response and makes it easy to understand.

The Standard Categories are listed as follows:

  1. Informational responses (1xx) – denotes that the request has been received
  2. Successful responses (2xx) –denotes that the request has been received and have been accepted.
  3. Redirects (3xx)- denotes that some actions need to be taken in order to complete the request.
  4. Client errors (4xx) – denotes that the syntax is not as per the expectations or something is wrong.
  5. Server errors (5xx) – denotes that the server is not able to process the request as of now.

Now let’s learn about different categories with some of the common API codes that we will be seeing while working with the HTTP request

Information Responses (1xx)

An informational response provides an indication that the HTTP request was received by the server and has been understood. it’s issued on a tentative basis whereas request process continues. But it’s just a prior indication before the final response. The message consists solely of the response status line and optional header, which is ended with an empty line. 

Following is the list of the common Response codes:

Status CodeDescription
100 ContinueIt means that the HTTP request header have been received and the client should now proceed to send the body of the request. It means that the request is accepted and has not been rejected by the server.   It indicates that the client can continue to send the remaining part of the request, if the whole request was not sent.   Now it’s the responsibility of the server to send a final response after the request has been completed.
101 Switching ProtocolThis code is sent in response to upgrade the request header from the client and shows the protocol the server is switching to .
102 Processing ProtocolIt tells that the request was successfully received by the serve and its being currently processed but as of now there is not response ready yet.
103 Early HintsIt is used with the Link Header, which helps the serve to preload the resources while the response is being prepared.

Success Response(2xx)

The Class of response status code comes into the action once the request has been sent by the client. It indicates that the HTTP request sent by the Client machine has been received, understood and accepted. It provides a Green light to the REST API request, stating that it was successfully carried out.

The value that is provided in return with the response is entirely dependent on the HTTP method type that have been used while the HTTP request was sent:

  • GET: The resource has been fetched and is transmitted in the message body.
  • HEAD: The headers are in the message body.
  • PUT or POST: The resource describing the result of the action is transmitted in the message body.
  • TRACE: The message body contains the request message as received by the server

Let’s discuss about the different Codes that you will be seeing:

Status CodeDescription
200 OKThis is the expected response from every HTTP request that we are sending out to see a success response. But again the actual response will depend on the HTTP method type that we are using in the request.
201 CreatedThis code denotes that a new resource has been created due to the provided HTTP request.   This response is usually received whenever we are using with the POST or the PUT request.
202 AcceptedIt means the request was successfully received but the processing of the request has not yet been completed.   This request might be processed or might not be, or maybe disallowed when the processing occurs.   Its allow the server to accept multiple process request at a single time.
203 Non-Authoritative InformationThis status code means that the response that have been returned is not as the original response that was provided from the origin server. It might have taken the response from the Local copy.   Usually this code is used when some minor backup resources are created.
204 No ContentThe HTTP request has been successfully Processed by the server, but it is not returning any content.   The content might not be there for returning, but the headers will be helpful.  
205 Reset ContentThe HTTP request has been successfully Processed by the server, and its asking the user-agent to reset the document view.   And it won’t be returning any content.
207 Multi-StatusProvides the description about the multiple resources , for different situation where different kinds of status codes might be appropriate .
208 Already ReportedThe individuals members of a DAV binding have as of now been listed in  previous portion of the (multistatus) HTTP response, and are not being included once more.
226 IM UsedThe server has satisfied a GET HTTP Request for the resource allocated, and the HTTP response  could be a representation of the result of one or more instance-manipulations connected to the current occurrence.

Redirects(3xx)

As the name itself suggest that this kind of the status code ask the client to take some additional steps that will help to complete the HTTP response. These are generally used in the URL Redirection scenario.

The user has not to perform any additional steps in order to complete the request, it’s the User-agent who will have to take some extra action to process with the next redirection request. This might be done automatically.

Let’s discuss about the different Codes that you will be seeing:

Status CodeDescription
300 Multiple ChoicesThis status codes means that User-agent has now multiple responses to choose from. Depends on the client which ever required can be taken for further processing.
301 Moved PermanentlyThe URL that has been requested by the Client has now been changed from the previous URL. In the response we get the new changed URL.
302 Found (Previously “Moved temporarily”)This response code means that the URL that we were trying to fetch has been changes temporary. It might be even changed again in the future.
303 See OtherThe HTTP Response to the HTTP Request  can be found beneath another URI utilizing the GET HTTP Method..
304 Not Modified This status code means that the response is still the same, it has not been modified. The client app can use the same cached version of the response.   In this case no response will be sent again, since the client already has the cached copy.    
305 Use ProxyThis Response status code has been deprecated by the HTTP. It meant that certain request could only get a response if they were going through a particular proxy.   Due to main security constraints different HTTP clients don’t obey this HTTPS Response code.
306 Switch ProxyThis Response code is also not used anymore, it used to meant that whenever a request was being processed then it should be processed with the particular proxy.
307 Temporary RedirectThis Response code is used for the temporary re-direction to another URL for fetching the response for the Client HTTP Request.   And this should be done using the same method, rather than changing the HTTP method.   However the future  HTTP request should still use the same original URL .
308 Permanent RedirectThis Status code is usually sent out when the resource is no more available at the requested URL.   Now all the current request or the future request needs to be redirected to the new URL for the resource.

Client errors (4xx)

The Response status codes that falls under this category are mainly related to the error that are occurring due to the error in the request send by the client Application.

In order to resolve all these status codes, the developer would have to make some changes in their code or the request that they are trying to send to the server.

Let’s discuss about the different Codes that you will be seeing:

Status CodeDescription
400 Bad RequestThis denotes that there is client error due to which the server cannot process the request. This client error can be due to invalid request message framing, malformed request syntax, deceptive request routing or size too large.
401 UnauthorizedThis code refers to a condition where authentication provided by the user is either not provided or failed the validation. The client’s identity is not known to the server.
402 Payment RequiredThis response code was meant for future use either for digital cash or micropayment scheme, however currently no standard convention exists for its use.
403 ForbiddenThe client is unauthorized to access the requested content, hence the serve refuses to grant the requested source. However, unlike code 401, the server is aware of the client’s identity here.
404 Not FoundThe requested source has not been found. Subsequent requests by the client are permitted since the source might be available in the future.
405 Method Not AllowedThis code indicates that the request method is not supported for the requested source.
406 Not AcceptableThis code indicates that the though the server has performed the server driven content negotiation, but isn’t able to find any content satisfying the criteria given by the user agent.
407 Proxy Authentication RequiredThis code is very much similar to code 401, but the client must authenticate itself to a proxy first.
408 Request TimeoutThis code indicates that the server has timed out while waiting for the request. The client may re-initiate the request at a later time.
409 ConflictThis code indicates that there is a conflict in the current state of the resource for the sever to process the request.
410 GoneThis code refers to the condition where the requested source has been permanently deleted from the server, without providing any forwarding address. The clients must not request the resource in the future and search engines must remove the resource from their indices. i.e., they should purge the resource.
411 Length RequiredThis code indicates that the request does not specify the length of its content, which is required.
412 Precondition FailedThis code indicates that either one of the preconditions put forth by the requester on the request header fields have not been met by the server.
413 Payload Too LargeThis code was previously known as ‘Request Entity Too Large’ and indicates that the request made is larger than what the server can process.
414 URI Too LongThis code indicates that the URI request made by the client is longer than the server can interpret.
415 Unsupported Media TypeThis code indicates that the server has rejected the request made since the media format of the requested data is not supported by the server.
416 Range Not SatisfiableThis code indicates that the server cannot meet the client request since the portion of the file requested is out of bounds.
417 Expectation FailedThis code indicates that the server is unable to meet the requirements of the Expect-Request Header Field.
418 I’m a teapotThis code is not expected to be implemented by the actual HTTP servers. Here the server simply denies to cater to the request made.
421 Misdirected RequestThis indicates that the request was made to server that is not capable of producing a response.
422 Unprocessable EntityThis code indicates that the request though was well formed, but is unable to be followed citing semantic errors.
423 LockedThis simply indicates that the resource being accessed is locked.
424 Failed DependencyThis code indicates that the request made failed due its dependency on another request which actually failed, hence leading this outcome.
425 Too EarlyThis code indicates that the server feels the current request might be replayed, hence there is rick in processing it.
426 Upgrade RequiredThis code indicates that while the client continues using the present protocol, the server cannot process the request. However, if the client wishes to upgrade the protocol, the server might be willing to go ahead with the request.
428 Precondition RequiredThe origin server requires the request to be conditional. This response is intended to prevent the ‘lost update’ problem, where a client GETs a resource’s state, modifies it, and PUTs it back to the server, when meanwhile a third party has modified the state on the server, leading to a conflict.
429 Too Many RequestsThis code indicates that the user has made too many requests in a given amount of time.
431 Request Header Fields Too LargeThis code indicates that since an individual header field or collectively all header fields are too large, the server is unwilling to process the request.
451 Unavailable For Legal ReasonsThis code indicates that the requested resource cannot be legally provided.

Server errors (5xx)

These HTTP Status Error Codes are usually sent out so as when the server is incapable to process the request of the Client.

These Reponses codes are accompanied with the messages that would help in easy explanation of the scenario to the client application. These are applicable to any HTTP request method.

Let’s discuss about the different Codes that you will be seeing:

Status CodeDescription
500 Internal Server ErrorThis Status code is the generic error which is thrown which occurs dues to an unexpected condition.   Whenever a HTTP Request generates an exception that is not handled in the Exception than such Generic error is thrown which contains a generic message.
501 Not ImplementedThis Response Code is sent out when the HTTP request method is not recognized or the Client request cannot be completed.
502 Bad GatewayThe server was acting as a portal or intermediary and it got an  invalid HTTP Response  from the upstream server
503 Service UnavailableThe server isn’t prepared to handle the HTTP Request. Common reasons are a server that’s down for support or that’s over-burden.   This Status code is usually used for the temporary situations only.
504 Gateway TimeoutThis HTTP Status Code is sent out when the Request was not processed in the given interval of time.  
505 HTTP Version Not SupportedThe HTTP version used in the request is not supported by the server.
506 Variant Also NegotiatesThis code indicates that the chosen variant resource is not a proper end point in the negotiation process, since it is configured to engage in transparent content negotiation itself.
507 Insufficient StorageThis code indicates that the server is unable to store the representation needed to complete the request.
508 Loop DetectedThis code indicates that the server has detected an infinite loop while processing the request made.
510 Not ExtendedThis indicates that the server requires further extensions to the request in order to fulfil it.
511 Network Authentication RequiredThis code indicates that the client in order to gain access must authenticate itself.

All the above-defined API Status Codes are seen whenever the HTTP request and HTTPs response are exchanged between the Client and the Server.

Tejasvi Nanda

About the Author

Tejasvi Nanda