HTTP status codes cheat sheet for API developers (RFC 9110)

Status codes are the first thing every API client reads, and the first thing it gets wrong when they are inconsistent. A 200 with an error message inside, a 500 for a validation failure or a 403 where a 401 was meant all push work onto every developer who integrates with you.

This cheat sheet covers the status codes a typical REST or JSON API actually needs, with the rules from RFC 9110 (the current HTTP Semantics standard) and the IANA registry, both checked on 9 October 2026. Each entry says when to use the code, what headers go with it, and the common mistakes. Keep it open while you design endpoints or review a pull request.

The five classes in one table

The class matters more than the exact number. Clients, proxies and monitoring tools treat any unknown code as the x00 of its class, so a 4xx must always mean "the caller did something wrong" and a 5xx "we did".

2xx: success codes for APIs

3xx: redirects and caching

RFC 9110 keeps a historical note on 301 and 302: a user agent may change the request method from POST to GET when following them, and the standard points to 307 and 308 if that is undesired. For APIs, that settles it: use 307 or 308, because a client that silently turns your POST into a GET loses the request body.

4xx: client errors you will actually use

Authentication and permissions

• 401 Unauthorized means "not authenticated": no credentials, or invalid ones. RFC 9110 says a server generating a 401 MUST send a WWW-Authenticate header with at least one challenge, for example WWW-Authenticate: Bearer. MDN puts it plainly: semantically, 401 means "unauthenticated".
• 403 Forbidden means the server knows who you are, but you may not do this. The client should not retry with the same credentials.
• Hiding existence: RFC 9110 allows a server to answer 404 instead of 403 to hide that a forbidden resource exists. This is a good default for other tenants' records in multi-tenant APIs.

Requests that are wrong

400 or 422 for validation errors?

Both are defensible. RFC 9110 defines 422 for content whose type and syntax are correct but whose instructions cannot be processed, which describes most validation failures. Laravel follows that convention: its documentation says a failed validation on a request expecting JSON returns a 422 response with the errors. Many other APIs use 400 for everything the caller got wrong. Pick one, document it, and apply it consistently. Whichever you choose, return field-level detail in the body; RFC 9457 Problem Details is a standard format for that.

Renamed codes

RFC 9110 renamed two familiar codes: 413 is now Content Too Large (formerly Payload Too Large) and 422 is Unprocessable Content (formerly Unprocessable Entity). The numbers did not change, and libraries lag behind: in Node.js 24.19.0, http.STATUS_CODES[422] still returns "Unprocessable Entity" and [413] returns "Payload Too Large". Clients should never depend on the reason phrase; HTTP/2 and HTTP/3 do not even send one.

5xx: server errors

Your application code usually returns only 500 and 503. 502 and 504 normally come from nginx, a load balancer or a CDN in front of you, which makes them a useful hint during an incident: the problem is between the proxy and your app.

Codes to avoid or treat with care

• 418 is listed in the IANA registry as "(Unused)". It began as an April Fools' joke; do not use it in production APIs.
• 402 Payment Required is reserved for future use in RFC 9110. If you use it for billing problems, document exactly what it means in your API.
• 200 with an error body breaks retries, monitoring and caching. If the request failed, say so in the status code.
• Temporary registrations: the IANA registry currently lists 104 (Upload Resumption Supported) as a temporary registration expiring on 13 November 2026, tied to an IETF draft. Check the registry before relying on anything new.

Check status codes from the terminal

# Status code only
curl -s -o /dev/null -w "%{http_code}\n" https://example.com/api/orders/123

# Status line and headers (look for Location, Allow, Retry-After, WWW-Authenticate)
curl -si -X DELETE https://example.com/api/orders/123 | head -n 20

In Node.js, import { STATUS_CODES } from 'node:http' gives you a lookup table of names, which is handy for logs but, as noted above, not always the newest wording. In PHP, http_response_code(422) sets the status in plain PHP; frameworks such as Laravel and Symfony provide response helpers.

What to do next

1. List every endpoint and the status codes it can return; put them in your OpenAPI description.
2. Choose 400 or 422 for validation and use it everywhere.
3. Add the required headers: Location on 201, Allow on 405, WWW-Authenticate on 401, and Retry-After on 429 and 503 where you can.
4. Replace 301 and 302 with 307 and 308 for anything other than browser page moves.
5. Write one test per error path, so a refactor cannot quietly turn a 404 into a 500.

Consistent status codes are cheap documentation. When every endpoint follows the same rules, your API's clients need fewer special cases, and your logs tell you at a glance whether the caller or the server is at fault.