REST API Status Code Guide

Offers practical criteria for choosing the right status code for each situation in a REST API.

A well-designed REST API communicates the result of a request clearly through status codes. Use 200 OK for a successful read, 201 Created for resource creation (with the new URL in the Location header), and 204 No Content for a success with no body to return (such as a deletion).

Client errors are distinguished with 4xx. The standard choices are 400 Bad Request for malformed syntax, 401 Unauthorized when authentication is required, 403 Forbidden for no permission, 404 Not Found for a missing resource, 409 Conflict for a state conflict, 422 Unprocessable Content for a validation failure, and 429 Too Many Requests for too many requests.

Server errors are signaled with 5xx. Use 500 Internal Server Error for an unexpected exception and 503 Service Unavailable for overload or maintenance, sending a Retry-After header along with it when possible. Above all, consistently returning the same code for the same situation is what determines an API's usability.