Choosing HTTP status codes deliberately

What it is

RFC 9110 defines the classes and the individual codes. Some distinctions matter in practice: 401 means the request lacks valid credentials (and must carry WWW-Authenticate), 403 means the credentials are fine but the action is not allowed; 404 says the target does not exist (or the server chooses not to reveal it); 409 signals a conflict with the current state; 412 that a precondition such as If-Match failed; 428 (RFC 6585) that a precondition is required; 429 that the client is rate-limited; 503 that the server is temporarily unavailable, both ideally with Retry-After.

Why it matters

Clients, caches and agents decide on retries, re-reads and user messages from the code alone. A 200 with an error body defeats all of them.

How to apply

• Map each failure class in the domain to one code and one machine-readable problem type; document the mapping.
• Use 201 with the created resource's identifier or address for creations; 204 for successful deletes and revocations.
• Use 422 for well-formed but semantically invalid input if your API distinguishes it from 400; be consistent.
• Send Retry-After on 429 and 503 whenever you can compute it.

Pitfalls

Using 404 to hide authorisation decisions is legitimate but must be consistent. 302 for API redirects loses POST bodies in some clients; use 307/308. Custom codes outside the registered ranges confuse intermediaries.

What it is

RFC 9110 defines the classes and the individual codes. Some distinctions matter in practice: 401 means the request lacks valid credentials (and must carry WWW-Authenticate), 403 means the credentials are fine but the action is not allowed; 404 says the target does not exist (or the server chooses not to reveal it); 409 signals a conflict with the current state; 412 that a precondition such as If-Match failed; 428 (RFC 6585) that a precondition is required; 429 that the client is rate-limited; 503 that the server is temporarily unavailable, both ideally with Retry-After.

Why it matters

Clients, caches and agents decide on retries, re-reads and user messages from the code alone. A 200 with an error body defeats all of them.

How to apply

• Map each failure class in the domain to one code and one machine-readable problem type; document the mapping.
• Use 201 with the created resource's identifier or address for creations; 204 for successful deletes and revocations.
• Use 422 for well-formed but semantically invalid input if your API distinguishes it from 400; be consistent.
• Send Retry-After on 429 and 503 whenever you can compute it.

Pitfalls

Using 404 to hide authorisation decisions is legitimate but must be consistent. 302 for API redirects loses POST bodies in some clients; use 307/308. Custom codes outside the registered ranges confuse intermediaries.

Access-controlled resources

For resources that exist only for some clients, returning 403 for existing-but-forbidden and 404 for non-existent identifiers reveals which identifiers exist. Many APIs return 404 for both deliberately. Decide per resource whether existence is public information, document the choice, and apply it consistently.