REST API Status Codes: what they are and how they work

HTTP status codes, or Status Codes, are the three-digit codes that indicate the outcome of a communication between clients and servers using the HTTP protocol, such as web browsers and API applications.

These codes, which generally remain hidden from the user of the service, allow the client to know the outcome of its request even before analysing the payload, which is the actual response.

Among the most common HTTP Codes are HTTP Status 404, which appears when trying to connect to a web page that does not exist, and HTTP Status 500, which indicates a server error. Even successful requests, however, have their own codes: let's see what they are and what they indicate.

HTTP Status Codes in the REST API

The HTTP protocol is a method of transporting information widely used in client-server architectures, which has also found perfect application in the context of REST API calls.

In API calls, exactly what happens when, while surfing the Internet, an HTTP client asks a server for a resource: when the API client makes its request, the server responds by sending the HTTP Status Code indicating the type of response. What changes is the content of the response, or payload, which instead of containing an HTML page contains a json.

HTTP Codes are identical for all applications communicating via this protocol, and form part of an HTTP server's response.

What does a REST API response look like?

When an API client queries a server, it receives back a response that contains several pieces of information, and which, apart from technical specifications, includes some basic sections:

• HTTP status codes: these consist of three digits. They indicate the outcome of the communication and give information to the client on how to proceed;
• Header: contains the header attributes, which generally concern the format of the request body, the response cache time, and above all the permissions available to the client;
• Payload: this is the actual content of the API response, that which contains the data.

HTTP Status Codes are an integral part of an API response: their transmission allows the client to know what happened during the transfer even before analysing the content of the response. An HTTP Status 403, for instance, indicates that the client is authenticated but cannot access the requested resource. A Status Code 200, on the other hand, means that the request was successful and that the server returned the requested data.

HTTP Status Codes: What are they

HTTP status codes are divided into five classes, each of which begins with a digit indicating the type of response:

• 1xx - Information message: this type of response indicates that the server has received the request and is processing it;
• 2xx - Success Message: the request has been received, understood and processed correctly by the server;
• 3xx - Redirection Response: informs the client that it must perform additional actions to fulfil the request (e.g. when a resource is transferred, the HTTP Status 301 asks to point to the new Url);
• 4xx - Client Error Message: appears e.g. when credentials are invalid or the request has been mistyped;
• 5xx - Server error response: indicates that the server did not comply with the request because it encountered an error or could not handle the request.
  Each response type, in turn, includes several possible messages. Here are the most common ones.

Response Code HTTP 1xx: Informational Message

Information messages are sent when the request has been received by the server and is continuing with the processing of the request: they are often used to prevent the client from time-out while waiting for a response, but may also indicate that further information needs to be sent to complete the request.

• 100 - Continue: the initial part of the request has been received and the server asks to send the rest (for example: it has received the Header with the credentials and asks for the Payload to be sent);
• 101 - Change of protocol: the client has asked to change the protocol in use and the server communicates the change of protocol in the connection;
• 102 - Processing: indicates that the server is still processing the request.

HTTP Codes 2xx: Success

Success messages indicate that the request was received and processed successfully. This does not necessarily mean that the client will get what it wanted: in fact, the server's response may even be devoid of content.

• 200 - OK: indicates that the request was successful and that the server returned the requested data;
• 201 - Created: means that the request was successful and the server has created a new resource;
• 204 - No content: the request was successful but there is no data to transfer.

HTTP Codes 3xx: Redirection Responses

HTTP codes beginning with 3 indicate that the client must perform further actions to satisfy the request: they are used, for example, when the requested resource has been moved to a different location.

• 301 - Moved Permanently: the resource has been moved to a new Url, so the client must update the links and point to the new address;
• 303 - See Other: indicates that the response is available at a different address, so the client must make a GET request to that Url to retrieve it.

HTTP error codes: 4xx

Error codes beginning with the number 4 are perhaps the most dreaded by API client users, as they indicate that the request cannot be fulfilled due to an error on the part of the client, which may have messed up the syntax or lacked the necessary permissions. The most common HTTP 400 Status Codes are:

• Error 400 - Bad request: The request is invalid or not written in the correct manner;
• Error 401 - Unauthorised: The client does not have authorisation to access the resource;
• Error 403 - Forbidden: The client is authenticated but not authorised to access the request;
• Error 404 - Not Found: The requested resource was not found on the server:
• Error 408 - Request Timeout: The time to send the request has expired and the server has terminated the connection;
• Error 429 - Too Many Requests: Means that the client made too many requests in a short period of time, where call limits exist.

Error messages 500: Server errors

Error messages do not only concern the client: there are also internal server errors, which are indicated by a three-digit code starting with 5:

• 500 - Internal server error: this is a generic code indicating a server error that prevented it from fulfilling the request;
• 502 - Bad Gateway: a server acting as a gateway or proxy received an invalid response from an upstream server;
• 503 - Service Unavailable: means that the server is temporarily unable to handle the request, for example because it is undergoing maintenance or there is a spike in traffic.

 

Access reliable, high-quality data!

Discover over 400 services

in the Marketplace Openapi.com

DISCOVER NOW