Skip to main content

4.6. Using HTTP Status Codes

4.6. Using HTTP Status Codes​

Applications that use HTTP MUST only use registered HTTP status codes. They SHOULD use the most specific applicable status code, although they are not limited to those defined in [HTTP]; other status codes can be used as long as they are registered in the "HTTP Status Codes" registry.

When specifying how status codes are used, applications SHOULD focus on their generic semantics rather than their specific meaning in a particular context. For example, it's appropriate to say:

If the request succeeds, the server sends a 200 OK response.

but not:

The server sends a 200 OK response when the user is authenticated and authorized to access the resource.

The latter is too specific because it conflates several things: success, authentication, and authorization. A more appropriate statement would be:

If the request is successful, the server sends a 200 OK response. If authentication is required but not provided, the server sends a 401 Unauthorized response. If the client is not authorized to access the resource, the server sends a 403 Forbidden response.

Applications SHOULD NOT define new status codes. In the rare cases where a new status code is truly necessary, it MUST be registered following the procedure in [HTTP] Section 16.2.

When choosing a status code, the general principle is to select the most specific one that applies. The status code should convey the primary reason for the response.

For example, if a request fails because the resource doesn't exist, 404 Not Found is appropriate. If it fails because the client isn't authorized to access it, 403 Forbidden is appropriate, even though the resource might not exist.

Applications SHOULD use the following status codes appropriately:

  • 200 OK for successful requests where the response contains a representation.

  • 201 Created for successful requests that result in the creation of a new resource.

  • 202 Accepted for requests that have been accepted for processing but where processing hasn't been completed.

  • 204 No Content for successful requests where there's no representation to send.

  • 301 Moved Permanently or 308 Permanent Redirect for resources that have moved permanently.

  • 302 Found or 307 Temporary Redirect for resources that have moved temporarily.

  • 304 Not Modified for conditional requests where the resource hasn't changed.

  • 400 Bad Request for malformed requests.

  • 401 Unauthorized for requests that require authentication.

  • 403 Forbidden for requests where the client isn't authorized.

  • 404 Not Found for requests to non-existent resources.

  • 405 Method Not Allowed for requests using an inappropriate method.

  • 406 Not Acceptable when the server can't generate a representation that the client will accept.

  • 409 Conflict when the request conflicts with the current state of the resource.

  • 410 Gone for resources that existed but have been permanently removed.

  • 415 Unsupported Media Type when the request's Content-Type isn't supported.

  • 500 Internal Server Error for server-side errors.

  • 501 Not Implemented when the server doesn't support the requested functionality.

  • 503 Service Unavailable when the server is temporarily unable to handle the request.

Last updated on