1. The Semantic Importance of HTTP Status Codes
Hypertext Transfer Protocol status codes are standardized three-digit integers defined across RFC 7231 and RFC 9110. They communicate the operational result of a client request to browsers, API gateways, reverse proxies, and caching layers.
Misusing status codes—such as returning a 200 OK response containing an {"error": true} body—breaks upstream edge caches (Cloudflare, Fastly), confuses monitoring telemetry, and violates semantic REST principles.
2. Critical Status Codes Every Engineer Must Master
2xx Success
- 200 OK: Standard response for successful synchronous operations.
- 201 Created: The request succeeded and led to the creation of a new persistent resource (typically paired with a
Locationheader). - 204 No Content: The action was fulfilled successfully, but the server does not need to return an entity-body (common in
DELETEactions).
4xx Client Errors
- 400 Bad Request: The server cannot process the request due to malformed syntax, invalid JSON, or failing validation schemas.
- 401 Unauthorized: Semantically means unauthenticated. The client lacks valid authentication credentials.
- 403 Forbidden: The client is authenticated, but their identity lacks the authorization privileges required to access the target resource.
- 404 Not Found: The requested resource does not exist or the server wishes to obscure its existence from unauthorized callers.
- 429 Too Many Requests: Rate limiting triggered. RFC standards suggest attaching a
Retry-Afterheader.
5xx Server Errors
- 500 Internal Server Error: An unhandled exception or critical crash occurred inside server-side code execution.
- 502 Bad Gateway: An edge proxy received an invalid or corrupt response from an upstream backend server.
- 503 Service Unavailable: The server is temporarily overloaded or undergoing maintenance.
- 504 Gateway Timeout: An intermediary proxy did not receive a timely response from an upstream process.
3. Designing Clean API Error Payloads
Pair HTTP status codes with machine-readable error bodies (such as RFC 7807 Problem Details for HTTP APIs):
{
"type": "https://api.devtools-web.com/errors/invalid-payload",
"title": "Unprocessable Entity",
"status": 422,
"detail": "Field 'email' must contain a valid domain address.",
"instance": "/v1/users/create"
}