Home REST Security Cheat Sheet - HTTP Return Code

REST Security Cheat Sheet - HTTP Return Code


Why HTTP status code is important for REST API

HTTP status codes play a critical role in REST API as they provide a way for the server to communicate the outcome of an API request to the client. When designing REST API, don’t just use 200 for success or 404 for error. Always use the semantically appropriate status code for the response. Let’s take a look at some ways HTTP status codes are important to REST-based APIs.

  • Consistent communication standards

    When designing REST-based APIs, consider the significance of HTTP status codes. They offer a universal method for servers to communicate response status to clients. Using codes like 200 (OK) and 404 (Not Found) ensures cross-language compatibility, a key advantage of REST-based architecture.

  • Clarity in requests outcomes

    HTTP status codes offer immediate clarity to clients without the need to inspect the response body. Clients rely on these codes to determine the request’s success or failure. API providers benefit from using standard HTTP status codes and should avoid creating custom ones. For instance, a new resource creation should return 201, not 200, to ensure precision in client expectations. By using the right status codes, clients can confidently understand the request outcome and streamline their implementations.

  • Troubleshooting made easy

    HTTP status codes simplify API troubleshooting. For instance, some dashboard allows filtering requests by status codes, making it easy to identify issues, excluding 300 status codes. Clients can swiftly pinpoint the problem source; for example, encountering a 400 status code signals a client-side issue, triggering appropriate error handling.

  • Uniform error handling

    HTTP status codes offer a uniform approach for handling errors and exceptions. For instance, when a client encounters a 404 status code, it gracefully manages the situation, like redirecting or displaying an error message. Clients can rely on status codes, avoiding the need for distinct error handling for each API they consume.

  • API security

    HTTP status codes enhance API security. A 401 or 403 status code signifies the lack of permission to access a resource, safeguarding sensitive data and thwarting security risks.

  • Indicate progress

    HTTP status codes can track lengthy operations, like file uploads. A 202 code signifies request receipt and processing, while a 200 code marks completion.

REST Specific HTTP Status Code

Here is a non-exhaustive selection of security related REST API status codes. Use it to ensure you return the correct code.

200OKResponse to a successful REST API action. The HTTP method can be GET, POST, PUT, PATCH or DELETE.
201CreatedThe request has been fulfilled and resource created. A URI for the created resource is returned in the Location header.
202AcceptedThe request has been accepted for processing, but processing is not yet complete.
204No ContentUsually sent out in response to a PUT, POST, or DELETE request when the REST API declines to send back any status message or representation in the response message’s body.
301Moved PermanentlyPermanent redirection.
302FoundA common way of performing URL redirection.
304Not ModifiedCaching related response that returned when the client has the same copy of the resource as the server.
307Temporary RedirectTemporary redirection of resource.
400Bad RequestThe request is malformed, such as message body format error.
401UnauthorizedWrong or no authentication ID/password provided.
403ForbiddenIt’s used when the authentication succeeded but authenticated user doesn’t have permission to the request resource.
404Not FoundWhen a non-existent resource is requested.
405Method Not AcceptableThe error for an unexpected HTTP method. For example, the REST API is expecting HTTP GET, but HTTP PUT is used.
406UnacceptableThe client presented a content type in the Accept header which is not supported by the server API.
412Precondition FailedThe client specified one or more preconditions in its request headers, effectively telling the REST API to carry out its request only if certain conditions were met.
413Payload too largeUse it to signal that the request size exceeded the given limit e.g. regarding file uploads.
415Unsupported Media TypeThe requested content type is not supported by the REST service.
429Too Many RequestsThe error is used when there may be DOS attack detected or the request is rejected due to rate limiting.
500Internal Server ErrorAn unexpected condition prevented the server from fulfilling the request. Be aware that the response should not reveal internal information that helps an attacker, e.g. detailed error messages or stack traces.
501Not ImplementedThe REST service does not implement the requested operation yet.
503Service UnavailableThe REST service is temporarily unable to process the request. Used to inform the client it should retry at a later time.

Common Mistakes

  1. Wrong status code - One common mistake is using the wrong HTTP status code, like responding with a 200 OK for an error or a 404 Not Found for a successful request.

  2. Insufficient information - Another common mistake is providing insufficient information in the response body. The status code offers a summary, but the response body should contain more detailed results.

  3. Using non-standard status codes - While using non-standard HTTP status codes is possible, it can lead to compatibility issues and confusion for clients. To ensure broad client compatibility, it’s best to stick with standard HTTP status codes.

  4. Not updating the documentation - Maintain current and precise API documentation, including HTTP status codes info. Failing to update updates can cause client confusion and misunderstandings.

  5. Not testing thoroughly - Testing HTTP status codes in your REST API is crucial. Thoroughly validate your implementation with both automated and manual testing for accuracy and reliability.

Best Practices

  1. Use Standard HTTP Status Codes - Prefer standard HTTP status codes for a consistent user experience. Custom codes can confuse users and hinder issue diagnosis.

  2. Be Consistent - Consistent use of HTTP status codes ensures clear client understanding for a meaningful user experience.

  3. Use Appropriate Status Codes - Select the right HTTP status code for each response. For success, go with 200 OK, for resource creation, use 201 Created, and for bad requests, opt for 400 Bad Request.

  4. Provide Detailed Error Information - When using an error status code, offer detailed error info for client troubleshooting. Include a descriptive message, API docs reference, and relevant error codes.

  5. Avoid Overloading Status Codes - Avoid overloading a single status code to mean different things in different contexts. It causes confusion and hinders issue diagnosis.

  6. Document the API - Document the API, including the HTTP status codes used and their meanings, to help ensure that the API is well understood by developers.


List of HTTP status code

All HTTP response status codes are separated into five classes or categories. The first digit of the status code defines the class of response, while the last two digits do not have any classifying or categorization role. There are five classes defined by the standard:

1XX information response

100ContinueThe server has received the request headers and the client should proceed to send the request body (in the case of a request for which a body needs to be sent; for example, a POST request). Sending a large request body to a server after a request has been rejected for inappropriate headers would be inefficient. To have a server check the request’s headers, a client must send Expect: 100-continue as a header in its initial request and receive a 100 Continue status code in response before sending the body. If the client receives an error code such as 403 (Forbidden) or 405 (Method Not Allowed) then it should not send the request’s body. The response 417 Expectation Failed indicates that the request should be repeated without the Expect header as it indicates that the server does not support expectations (this is the case, for example, of HTTP/1.0 servers).
101Switching ProtocolsThe requester has asked the server to switch protocols and the server has agreed to do so.
102Processing (WebDAV; RFC 2518)A WebDAV request may contain many sub-requests involving file operations, requiring a long time to complete the request. This code indicates that the server has received and is processing the request, but no response is available yet.[3] This prevents the client from timing out and assuming the request was lost. The status code is deprecated.
103Early Hints (RFC 8297)Used to return some response headers before final HTTP message.

2XX successful

200OKIndicates that the request has succeeded.
201CreatedIndicates that the request has succeeded and a new resource has been created as a result.
202AcceptedIndicates that the request has been received but not completed yet. It is typically used in log running requests and batch processing.
203Non-Authoritative InformationIndicates that the returned metainformation in the entity-header is not the definitive set as available from the origin server, but is gathered from a local or a third-party copy. The set presented MAY be a subset or superset of the original version.
204No ContentThe server has fulfilled the request but does not need to return a response body. The server may return the updated meta information.
205Reset ContentIndicates the client to reset the document which sent this request.
206Partial ContentIt is used when the Range header is sent from the client to request only part of a resource.
207Multi-Status (WebDAV)An indicator to a client that multiple operations happened, and that the status for each operation can be found in the body of the response.
208Already Reported (WebDAV)Allows a client to tell the server that the same resource (with the same binding) was mentioned earlier. It never appears as a true HTTP response code in the status line, and only appears in bodies.
226IM UsedThe server has fulfilled a GET request for the resource, and the response is a representation of the result of one or more instance-manipulations applied to the current instance.

3XX redirection

300Multiple ChoicesThe request has more than one possible response. The user-agent or user should choose one of them.
301Moved PermanentlyThe URL of the requested resource has been changed permanently. The new URL is given by the Location header field in the response. This response is cacheable unless indicated otherwise.
302FoundThe URL of the requested resource has been changed temporarily. The new URL is given by the Location field in the response. This response is only cacheable if indicated by a Cache-Control or Expires header field.
303See OtherThe response can be found under a different URI and SHOULD be retrieved using a GET method on that resource.
304Not ModifiedIndicates the client that the response has not been modified, so the client can continue to use the same cached version of the response.
305Use Proxy (Deprecated)Indicates that a requested response must be accessed by a proxy.
306(Unused)It is a reserved status code and is not used anymore.
307Temporary RedirectIndicates the client to get the requested resource at another URI with same method that was used in the prior request. It is similar to 302 Found with one exception that the same HTTP method will be used that was used in the prior request.
308Permanent Redirect (experimental)Indicates that the resource is now permanently located at another URI, specified by the Location header. It is similar to 301 Moved Permanently with one exception that the same HTTP method will be used that was used in the prior request.

4XX client errors

400Bad RequestThe request could not be understood by the server due to incorrect syntax. The client SHOULD NOT repeat the request without modifications.
401UnauthorizedIndicates that the request requires user authentication information. The client MAY repeat the request with a suitable Authorization header field
402Payment Required (Experimental)Reserved for future use. It is aimed for using in the digital payment systems.
403ForbiddenUnauthorized request. The client does not have access rights to the content. Unlike 401, the client’s identity is known to the server.
404Not FoundThe server can not find the requested resource.
405Method Not AllowedThe request HTTP method is known by the server but has been disabled and cannot be used for that resource.
406Not AcceptableThe server doesn’t find any content that conforms to the criteria given by the user agent in the Accept header sent in the request.
407Proxy Authentication RequiredIndicates that the client must first authenticate itself with the proxy.
408Request TimeoutIndicates that the server did not receive a complete request from the client within the server’s allotted timeout period.
409ConflictThe request could not be completed due to a conflict with the current state of the resource.
410GoneThe requested resource is no longer available at the server.
411Length RequiredThe server refuses to accept the request without a defined Content- Length. The client MAY repeat the request if it adds a valid Content-Length header field.
412Precondition FailedThe client has indicated preconditions in its headers which the server does not meet.
413Request Entity Too LargeRequest entity is larger than limits defined by server.
414Request-URI Too LongThe URI requested by the client is longer than the server can interpret.
415Unsupported Media TypeThe media-type in Content-type of the request is not supported by the server.
416Requested Range Not SatisfiableThe range specified by the Range header field in the request can’t be fulfilled.
417Expectation FailedThe expectation indicated by the Expect request header field can’t be met by the server.
418I’m a teapot (RFC 2324)It was defined as April’s lool joke and is not expected to be implemented by actual HTTP servers. (RFC 2324)
420Enhance Your Calm (Twitter)Returned by the Twitter Search and Trends API when the client is being rate limited.
422Unprocessable Entity (WebDAV)The server understands the content type and syntax of the request entity, but still server is unable to process the request for some reason.
423Locked (WebDAV)The resource that is being accessed is locked.
424Failed Dependency (WebDAV)The request failed due to failure of a previous request.
425Too Early (WebDAV)Indicates that the server is unwilling to risk processing a request that might be replayed.
426Upgrade RequiredThe server refuses to perform the request. The server will process the request after the client upgrades to a different protocol.
428Precondition RequiredThe origin server requires the request to be conditional.
429Too Many RequestsThe user has sent too many requests in a given amount of time (“rate limiting”).
431Request Header Fields Too LargeThe server is unwilling to process the request because its header fields are too large.
444No Response (Nginx)The Nginx server returns no information to the client and closes the connection.
449Retry With (Microsoft)The request should be retried after performing the appropriate action.
450Blocked by Windows Parental Controls (Microsoft)Windows Parental Controls are turned on and are blocking access to the given webpage.
451Unavailable For Legal ReasonsThe user-agent requested a resource that cannot legally be provided.
499Client Closed Request (Nginx)The connection is closed by the client while HTTP server is processing its request, making the server unable to send the HTTP header back.

5XX server errors

500Internal Server ErrorThe server encountered an unexpected condition that prevented it from fulfilling the request.
501Not ImplementedThe HTTP method is not supported by the server and cannot be handled.
502Bad GatewayThe server got an invalid response while working as a gateway to get the response needed to handle the request.
503Service UnavailableThe server is not ready to handle the request.
504Gateway TimeoutThe server is acting as a gateway and cannot get a response in time for a request.
505HTTP Version Not Supported (Experimental)The HTTP version used in the request is not supported by the server.
506Variant Also Negotiates (Experimental)Indicates that the server has an internal configuration error: the chosen variant resource is configured to engage in transparent content negotiation itself, and is therefore not a proper endpoint in the negotiation process.
507Insufficient Storage (WebDAV)The method could not be performed on the resource because the server is unable to store the representation needed to successfully complete the request.
508Loop Detected (WebDAV)The server detected an infinite loop while processing the request.
510Not ExtendedFurther extensions to the request are required for the server to fulfill it.
511Network Authentication RequiredIndicates that the client needs to authenticate to gain network access.


About Myself

Please reach out to connect with me via Linkedin.

This post is licensed under CC BY 4.0 by the author.