</>
ProtocolCodes
HTTP

Which HTTP Error Code Should I Return?

Use this decision tree to select the correct HTTP error status code for your API or web application. Answer a series of yes/no questions about the nature of the request and what went wrong. Covers all common client errors (4xx) and server errors (5xx).

Decision Steps

Is the request itself syntactically malformed or missing required fields?

Does the endpoint require authentication and the request provides no credentials (or clearly invalid ones)?

Are the credentials valid but the user lacks permission to access this resource?

Does the requested resource not exist?

Does the resource exist but the HTTP method (e.g., DELETE, PUT) is not supported on it?

Would the request cause a conflict with the current state of the resource (e.g., duplicate entry, edit conflict)?

Is the request well-formed but contains semantic validation errors (e.g., invalid field values, business rule violations)?

Has the client exceeded a rate limit or quota?

Did an unexpected error occur inside your server (bug, unhandled exception)?

Possible Outcomes

400-bad-request Malformed or missing required fields
401-unauthorized No valid authentication credentials
403-forbidden Authenticated but lacks permission
404-not-found Resource does not exist
405-method-not-allowed HTTP method not supported on resource
409-conflict Request conflicts with current resource state
422-unprocessable-content Semantic validation failure
429-too-many-requests Rate limit or quota exceeded
500-internal-server-error Unexpected server-side bug
503-service-unavailable Server temporarily down or overloaded

Related Status Codes

HTTP 400 HTTP 401 HTTP 403 HTTP 404 HTTP 405 HTTP 409 HTTP 422 HTTP 429 HTTP 500 HTTP 503

Related Terms

Status Code REST (Representational State Transfer) Rate Limiting Authentication Problem Details (RFC 9457) HTTP Semantics (RFC 9110)