Using HTTP status codes correctly: the client's first branching point

What it is

RFC 9110 defines the five classes and the individual codes; a client must recognize the class from the first digit and treat an unknown code like the x00 code of its class. A few distinctions matter most in practice: 401 means missing or invalid credentials, and the server must send a WWW-Authenticate header with it; 403 means the authentication is fine but the action is not permitted. 404 says the target does not exist, or that the server does not want to reveal that it exists. 409 reports a conflict with the current state, 412 a failed precondition such as If-Match, and 422 a request that is syntactically correct but cannot be processed in terms of its content. RFC 6585 adds 428 (precondition required) and 429 (too many requests), the latter optionally with Retry-After; 503 means temporary unavailability, likewise with Retry-After where the wait time can be determined.

Why it matters

A client sees the code before it parses the body; libraries, proxies and caches branch on it alone. Many clients retry a 503 or 429 but not a 400 or 422; a 304 saves the transfer, and a 201 provides the address of the new resource. An agent that operates an API based on its documentation needs this convention so it does not have to guess on every error, and so that after a timeout it does not repeat a request that has already taken effect.

How to apply

• Map each error class of the domain to exactly one code and one machine-readable problem type; the table belongs in the API documentation.
• Answer creation with 201 and a Location header or the identifier in the body; answer successful deletion and revocation with 204 and no body.
• Use 400 for syntactically broken input and 422 for input that is invalid in content, or use only one of the two, but consistently.
• Require preconditions using If-Match and entity tags and answer failures with 412; if you want to enforce them, answer requests without a precondition with 428.
• Send Retry-After with 429 and 503 whenever the wait time is known; clients and agents then honor it instead of retrying immediately.
• For redirects in APIs, use 307 or 308, which preserve the method and body; with 301 and 302, RFC 9110 allows a client to change POST to GET for historical reasons.

Pitfalls

Using 404 to hide authorization decisions is legitimate, but it must be applied consistently, otherwise the inconsistency reveals that the resource exists. Custom codes outside the registered ranges confuse intermediaries. A 200 with {"error": ...} in the body gets cached, is not retried, and is counted as a success by monitoring.

Partial success in batch requests

A request that processes several items has several outcomes. The status code describes the request as a whole: 200 (or 207 Multi-Status per RFC 4918) if it was accepted and processed, 4xx only if it was invalid as a whole. Each item carries its own status and, where applicable, its own problem object in the response body, at a documented location; GraphQL handles field errors alongside data in the same way. Monitoring counts item errors separately from request errors, so that a 200 in which ninety percent of the items failed is not treated as a success. For everything else the article's rule stands: an error that affects the entire request belongs in the status code, not in a 200.