Understanding HTTP status codes

Status codes are the server telling you what happened in one number. Learn the shape of each class and you can debug most APIs without reading a manual.

The five classes

The mental model: 4xx means fix your request, 5xx means it is not your fault.

The ones worth memorizing

Success

• 200 OK, the default happy path
• 201 Created, use after a successful POST that made a resource
• 204 No Content, success but nothing to return (common for DELETE)

Redirects

• 301 Moved Permanently, update your bookmarks and links
• 302 Found, temporary redirect
• 304 Not Modified, your cached copy is still good

Client errors

• 400 Bad Request, malformed input
• 401 Unauthorized, you are not authenticated (misnamed, really means unauthenticated)
• 403 Forbidden, authenticated but not allowed
• 404 Not Found
• 409 Conflict, e.g. a duplicate or a version clash
• 422 Unprocessable Entity, syntactically fine but semantically invalid
• 429 Too Many Requests, you got rate limited

Server errors

• 500 Internal Server Error, the catch-all crash
• 502 Bad Gateway, an upstream service returned garbage
• 503 Service Unavailable, overloaded or down for maintenance
• 504 Gateway Timeout, an upstream service took too long

401 vs 403

These trip people up. 401 means the server does not know who you are, so send credentials. 403 means it knows exactly who you are and the answer is still no.

Seeing them yourself

GET /api/users/42 HTTP/1.1
Host: example.com

HTTP/1.1 200 OK
Content-Type: application/json