Status Codes Are Contracts

Returning 200 OK with an error message in the body is a lie. Status codes communicate machine-readable semantics. Clients, proxies, and monitoring tools all read them. Get them right.

The Codes You Will Use Daily

2xx Success

• 200 — generic success, used with GET and PUT
• 201 — resource created, include Location header pointing to the new resource
• 204 — success with no body, common for DELETE

4xx Client errors

• 400 — malformed request syntax
• 401 — unauthenticated, no or invalid token
• 403 — authenticated but not authorized
• 404 — resource not found
• 409 — conflict, e.g. duplicate email
• 422 — valid syntax but semantic validation failed
• 429 — rate limit exceeded

5xx Server errors

• 500 — unhandled server error
• 503 — service unavailable, overload or maintenance

Common Mistakes

Using 400 for everything is lazy. Distinguish between a missing field (400), a field that fails business logic (422), and a duplicate resource (409). Clients need this precision to handle errors programmatically without parsing your error messages.