REST API Response Codes
The REST API uses the status line in the HTTP response (response status) to inform Clients about the outcome of the request.
In general, HTTP defines 40 standard status codes (response statuses) which are divided into five categories. Below are highlighted only those status codes that are frequently used in REST API.
| Category | Description |
|---|---|
| 1xx: Information | This class contains headers that inform about the transmission process. This is typically a preliminary response consisting only of the Status-Line and optional headers, ending with an empty line. There are no mandatory headers. Servers MUST NOT send 1xx HTTP/1.0 responses to clients. |
| 2xx: Success | This class of status codes indicates that the client's request was successfully received, understood, and accepted. |
| 3xx: Redirection | Codes in this class inform the client that another request must be made to successfully complete the operation, usually to a different URI. Five codes from this class, 301, 302, 303, 305, and 307, are directly related to redirection. |
| 4xx: Client Error | The 4xx class of codes is intended to indicate errors on the client's side. |
| 5xx: Server Error | Response codes starting with "5" indicate cases where the server knows that an error has occurred or it cannot process the request. |
See also: REST API Guide - https://restapitutorial.ru/httpstatuscodes.html
Status Codes in REST
Codes marked with an asterisk * are popular (frequently used) response codes.
200 * - (OK)
The request was successfully completed. The information returned with the response depends on the method used in the request, for example, when:
- GET The object corresponding to the requested resource was received.
- HEAD The header fields corresponding to the requested resource were received, the response body is empty.
- POST The requested action was performed.
201 * - (Created)
The REST API responds with a status code 201 for every creation of a resource in a collection. There may also be cases when a new resource is created as a result of some controller action, and in this case, 201 would also be an appropriate response.
A link (URL) to the new resource may be included in the response body or in the response header field Location.
The server must create the resource before returning the 201 status. If this cannot be done immediately, then the server should respond with a code 202 (Accepted).
202 - (Accepted)
The 202 response is typically used for actions that take a long time to process and cannot be completed immediately. This means that the request has been accepted for processing, but the processing is not yet complete.
Its purpose is to allow the server to accept the request for some other process (possibly a batch process that runs only once a day) without requiring that the user agent's connection to the server be maintained until the process is complete.
The entity returned with this response should contain an indication of the current status of the request and a pointer to the status monitor (location of the job queue) or some estimate of when the user can expect the request to be completed.
203 - (Non-Authoritative Information)
The provided information was taken not from the original source (but, for example, from a cache that may be stale, or from a backup that may have lost relevance). This fact is reflected in the response header and confirmed by this code. The provided information may or may not match the original data.
204 * - (No Content)
The status code 204 is typically sent in response to a PUT, POST, or DELETE request when the REST API refuses to send back any message about the state of the completed work.
The API may also send a 204 status in response to a GET request to indicate that the requested resource exists but has no data to add to the response body.
The 204 response should not contain a message body and thus always ends with the first empty line after the header fields.
205 - (Reset Content)
The server successfully processed the request and requires the client to reset the user input data. No data should be transmitted in the response (in the response body). It is usually applied to return to the initial state of the input form on the client.
206 - (Partial Content)
The server has fulfilled part of the GET request for the resource. The request MUST contain a Range header field (section 14.35), which indicates the desired range and MAY contain an If-Range header field (section 14.27), which makes the request conditional.
The request MUST contain the following header fields:
- Either a Content-Range field (section 14.16), which shows the range included in this request, or a Content-Type with the value multipart/byteranges, including Content-Range fields for each part. If there is a Content-Length field in the request header, its value MUST match the actual number of octets transmitted in the message body.
- Date
- ETag and/or Content-Location, if a 200 response was previously received for the same request.
- Expires, Cache-Control, and/or Vary, if the value of the field has changed since the last similar request was sent.
If the 206 response is the result of a conditional request that used a strong cache validator (see section 13.3.3), the response SHOULD NOT include any other entity headers. If such a response is the result of an If-Range request that used a "weak" validator, the response MUST NOT contain other entity headers; this prevents discrepancies between cached entity bodies and updated headers. Otherwise, the response MUST contain all entity headers that returned a 200 (OK) status for the same request.
The cache MUST NOT combine the 206 response with any previously cached data unless the ETag or Last-Modified fields match exactly (see section 16.5.4).
A cache that does not support Range and Content-Range headers MUST NOT cache 206 (Partial) responses.
300 - (Multiple Choices)
There are multiple representations of the resource available at the specified URI by MIME type, language, or other characteristics. The server sends a list of alternatives with the message, allowing the client to choose automatically or the user to make a selection.
If this is not a HEAD request, the response MUST include an object containing a list of characteristics and addresses from which the user or user agent can choose the most suitable one. The format of the object is determined by the data type provided in the Content-Type header field. Depending on the format and capabilities of the user agent, the selection of the most suitable option may be performed automatically. However, this specification does not define any standard for automatic selection.
If the server has a preferred representation, it MUST include the specific URI for that representation in the Location field; the user agent MAY use the Location header for automatic redirection to the suggested resource. This request may be cached unless explicitly stated otherwise.
301 - (Moved Permanently)
Redirection code. Indicates that the REST API resource model has been significantly changed and now has a new URL. The REST API should specify the new URI in the response header Location, and all future requests should be directed to the specified URI.
You are unlikely to use this response code in your API, as you can always use the API version for the new API while keeping the old one.
302 - (Found)
A common way to redirect to another URL. An HTTP response with this code must also provide the URL to redirect to in the Location header field. The user agent (e.g., browser) is prompted in the response with this code to make a second request to the new URL.
Many browsers have implemented this code in a way that violates the standard. They began to change the type of the original request, such as from POST to GET. Status codes 303 and 307 were added for servers that want to clearly define what response is expected from the client.
303 - (See Other)
The 303 response indicates that the controller resource has completed its work, but instead of sending an undesirable response body, it sends the client the URI of the resource. This may be the URI of a temporary status message for the resource or the URI for an already existing permanent resource.
The 303 status code allows the REST API to point to a resource without forcing the client to load the response. Instead, the client may send a GET request to the URL specified in the Location header.
The 303 response should not be cached, but the response to the second (redirected) request may be cacheable.
304 * - (Not Modified)
This status code is similar to 204 (No Content) since the response body should be empty. The key difference is that 204 is used when there is nothing to send in the body, while 304 is used when the resource has not changed since the version specified in the request headers If-Modified-Since or If-None-Match.
In such a case, there is no need to retransmit the resource, as the client still has a previously loaded copy.
All this saves resources for both the client and the server, as only the headers need to be sent and received, and there is no need for the server to generate content again, nor for the client to receive it.
305 - (Use Proxy)
Access to the requested resource MUST be done through the proxy server specified in the Location field. The Location field provides the proxy URI. The recipient is expected to repeat this request using the proxy. Response 305 can ONLY be generated by origin servers.
Note: the RFC 2068 specification does not explicitly state that the 305 response is intended to redirect a single request and that it should only be generated by the origin server. The omission of these restrictions has led to several significant security implications.
Many HTTP clients (such as Mozilla and Internet Explorer) handle this status incorrectly primarily for security reasons.
307 - (Temporary Redirect)
The 307 response indicates that the REST API will not process the client's request. Instead, the client should resend the request to the URL specified in the Location header. However, in future requests, the client should still use the original URL.
The REST API may use this status code to designate a temporary URL for the requested resource.
If the request method is not HEAD, the response body should contain a short note with a hyperlink to the new URL. If the 307 code was received in response to a request other than GET or HEAD, the client should not automatically redirect the request unless it can be confirmed by the client, as this may change the conditions under which the request was created.
308 - (Permanent Redirect) (experimental)
The request must be repeated at another address without changing the method used.
This and all subsequent requests need to be repeated at another URI. 307 and 308 (as proposed) are similar in behavior to 302 and 301 but do not require changing the HTTP method. Thus, for example, submitting a form to a "permanently redirected" resource can continue without issues.
400 * - (Bad Request)
This is a general client-side error status. Used when no other 4xx error code is appropriate. Errors may include incorrect request syntax, invalid request parameters, misleading requests, or router errors, etc.
The client should not repeat the exact same request.
401 * - (Unauthorized)
The 401 error message indicates that the client is trying to access a restricted resource without providing authorization data. It may have provided incorrect credentials or nothing at all. The response should include a WWW-Authenticate header field containing a description of the problem.
The client may repeat the request by specifying the appropriate authorization field in the header. If this has already been done, the 401 response will indicate that authorization for the specified credentials is not working. If the 401 response contains the same problem as the previous response, and the client has already attempted authentication at least once, the client user should present the data received in the response to the site owner, as it may help diagnose the problem.
402 - (Payment Required)
This code is reserved for future use.
It is intended for future use. Currently not in use. This code is intended for paid user services, not for hosting companies. It is meant that this error will not be issued by hosting providers in case of overdue payment for their services. Reserved starting from HTTP/1.1.
403 * - (Forbidden)
The 403 error indicates that the REST API refuses to fulfill the client's request, i.e., the client does not have the necessary permissions to access it. The 403 response is not a case where authorization is required (for authorization errors, the 401 code is used).
Attempting authentication will not help, and repeated requests are meaningless.
404 * - (Not Found)
Indicates that the REST API cannot match the client URL with a resource, but this URL may be accessible in the future. Subsequent client requests are permissible.
404 does not indicate whether the state is temporary or permanent. To indicate a permanent state, the 410 (Gone) code is used. 410 should be used if the server knows that the old resource is permanently unavailable and no longer has an address.
405 - (Method Not Allowed)
The API issues a 405 error when the client attempted to use an HTTP method that is not allowed for the resource. For example, the PUT method is specified, but there is no such method for the resource.
The 405 response should include an Allow header listing the supported HTTP methods, e.g., Allow: GET, POST.
406 - (Not Acceptable)
The API cannot generate the preferred data types requested by the client as specified in the Accept request header. For example, a client request for data in the format application/xml will receive a 406 response if the API can only return data in the format application/json.
In such cases, the client should resolve the data issue on their side before resending requests.
407 - (Proxy Authentication Required)
The response is similar to the 401 code, except that authentication is performed for the proxy server. The mechanism is similar to identification on the origin server.
The user must first authenticate through the proxy. The proxy server must return a Proxy-Authenticate header containing the resource request. The client may repeat the request along with the Proxy-Authenticate header. Introduced in HTTP/1.1.
408 - (Request Timeout)
The server's waiting time for receiving from the client has expired. The client did not provide the request in the time that the server was ready to accept it. The client MAY repeat the request without changes at any time.
For example, this situation may occur when uploading a large file to the server using POST or PUT. At some point during the transfer, the data source stopped responding, for example, due to a damaged disk or loss of connection with another computer on the local network. While the client is not sending anything, waiting for a response, the connection with the server is held. After a while, the server may close the connection on its side to allow other clients to make requests.
409 * - (Conflict)
The request cannot be processed due to a conflict in the current state of the resource. This code is permitted to be used only in cases where it is expected that the user can resolve this conflict themselves and repeat the request. The response body SHOULD include enough information for the user to understand the reason for the conflict. Ideally, the response should contain information that helps the user or their agent fix the issue. However, this is not always possible and is not required.
Conflicts usually occur during PUT requests. For example, during versioning, if the entity being accessed by the PUT method has changes that conflict with those made earlier by a third party, the server should use the 409 response to indicate to the user that this request cannot be completed. In this case, the response entity should contain a list of changes between the two versions in a format specified in the Content-Type header field.
410 - (Gone)
The server sends this response if the resource was previously available at the specified URL but has been deleted and is now unavailable. The server does not know the location of an alternative document, e.g., a copy. If the server suspects that the document may be restored soon, it is better to send the client a 404 code. Introduced in HTTP/1.1.
411 - (Length Required)
For the specified resource, the client must specify Content-Length in the request header. Without this field, it is not worth retrying the request to the server at this URI. This response is natural for POST and PUT type requests. For example, if files are being uploaded to the specified URI, and there is a limit on their size on the server. It would be wiser to check the Content-Length header at the very beginning and refuse the upload immediately than to provoke unnecessary load by breaking the connection when the client actually sends too large a message.
412 - (Precondition Failed)
Returned if none of the conditional fields in the request header were met.
When the client specifies that the REST API should perform the request only under certain conditions, and the API cannot fulfill the request under such conditions, a 412 response is returned.
This response code allows the client to write preconditions in the metadata of the current resource, thus preventing the requested method from being applied to the resource other than what is expected.
413 - (Request Entity Too Large)
Returned when the server refuses to process the request due to the request body being too large. The server may close the connection to stop further transmission of the request.
If the problem is temporary, it is recommended to include a Retry-After header in the server's response indicating the time after which a similar request can be repeated.
414 - (Request-URI Too Long)
The server cannot process the request due to the specified URL being too long. This rare error can be provoked, for example, when the client tries to pass long parameters via the GET method instead of POST, when the client ends up in a "black hole" of redirects (e.g., when the URI prefix points to its own ending), or when the server is under attack from a client trying to exploit vulnerabilities found on servers with fixed-length buffers for reading or processing the Request-URI.
415 - (Unsupported Media Type)
The 415 error message indicates that the API cannot process the media type provided by the client as specified in the Content-Type request header.
For example, the client's request contains data in the format application/xml, but the API is only capable of processing application/json. In this case, the client will receive a 415 response.
For example, the client uploads an image as image/svg+xml, but the server requires images to use a different format.
428 - (Precondition Required)
The 428 status code indicates that the origin server requires the request to be conditional.
Its typical use is to avoid the "lost update" problem, where the client GETs the state of the resource, modifies it, and SENDs it back to the server, when in the meantime a third party has changed the state on the server, leading to a conflict. By requiring that requests be conditional, the server can ensure that clients are working with the correct copies.
Responses with this status code MUST explain how to resend the request conditionally.
429 - (Too Many Requests)
The user has sent too many requests in a given amount of time.
Response representations SHOULD include details explaining the condition and MAY include a Retry-After header indicating how long to wait before making a new request.
431 - (Request Header Fields Too Large)
The 431 status code indicates that the server is unwilling to process the request because its header fields are too large. The request MAY be retried after reducing the size of the request header fields.
It can be used both in cases where the total of the request header fields is too large and in cases where one header field is malfunctioning. In the latter case, the response representation SHOULD indicate which header field was too large.
444 - (No Response) (Nginx)
Nginx response code. The server did not return any information and closed the connection. (useful as a deterrent for malicious software)
451 - (Unavailable For Legal Reasons)
Access to the resource is closed for legal reasons. The closest existing code is 403 Forbidden (the server understood the request but refuses to process it). However, in the case of censorship, especially when it is a requirement for providers to block access to a site, the server could not understand the request at all — it did not even receive it. A completely different code fits: 305 Use Proxy. However, such use of this code may not be liked by censors. Several options have been proposed for a new code, including "112 Emergency. Censorship in action" and "460 Blocked by Repressive Regime".
500 * - (Internal Server Error)
A general response when there is an error in the code. A universal message for an internal server error when no more specific message is appropriate.
Most web platforms automatically respond with this status code when an error occurs while executing the request handler code.
The 500 error never depends on the client, so it is reasonable for the client to repeat the exact same request and hope that this time the server will process it without errors.
501 - (Not Implemented)
The server either does not recognize the request method or lacks the capability to fulfill the request. This usually implies future availability (e.g., a new web service API feature).
If the method is known to the server but is not applicable to the resource, a 405 response should be returned.
502 - (Bad Gateway)
The server, acting as a gateway or proxy server, received an invalid response from the upstream server it accessed. Introduced in HTTP/1.0.
503 - (Service Unavailable)
The server cannot process the request due to temporary overload or maintenance. This is a temporary state from which the server will recover after some time. If this time is known, it MAY be conveyed in the Retry-After header.
504 - (Gateway Timeout)
The server, acting as a gateway or proxy server, did not receive a timely response from the upstream server for the current request.
505 - (HTTP Version Not Supported)
The server does not support or refuses to support the version of the HTTP protocol specified in the request.
510 - (Not Extended)
The request did not comply with the resource access policy. The server must send back all the information necessary for the client to send an extended request. Indicating how extensions inform the client is beyond the scope of this specification.
--
Sources and more detailed information: