Status codes people will actually act on
The dozen codes that carry real weight, and the difference between 400, 401, 403, 404, 409 and 422 when you are the one choosing.
4xx means the caller can fix it; 5xx means they cannot and it is your fault. That single split is what monitoring is built on, so an endpoint that returns 500 for a malformed body is not merely untidy. It pollutes your error rate and will page someone at three in the morning for a client bug.
401 means we do not know who you are; 403 means we know and you still cannot. Getting this backwards breaks clients, because a well-built client refreshes its token on 401 and gives up on 403, and mixing them produces either a refresh loop or a user stuck behind a login screen that will never help them. 404 versus 403 is a deliberate choice too: returning 404 for a resource that exists but is not yours hides its existence, which is sometimes exactly what you want.
409 Conflict is the underused one. It is the honest answer to "this request was valid but the current state says no": a duplicate email, a version mismatch, an already-cancelled order. Reaching for 400 for all of those flattens information the client needed. 422 is the pragmatic sibling for a well-formed body that fails semantic validation, and it is fine to use it as long as you use it consistently.
You should now be able to
- Choose the right class of code for a failure
- Distinguish authentication from authorisation in a response
- Explain what a 409 is for
Loading…