HTTP Status Codes and API Design Best Practices

Choosing the right HTTP status code is more nuanced than it appears. Here are guidelines that produce consistent, predictable APIs.

The Most Important Codes

200 OK for successful GET and PUT. 201 Created for successful POST that creates a resource. 204 No Content for successful DELETE. 400 Bad Request for validation errors. 401 Unauthorized for missing or invalid authentication. 403 Forbidden for authenticated but not authorized. 404 Not Found for missing resources. 409 Conflict for duplicate entries. 422 Unprocessable Entity for semantic validation errors.

400 vs 422

Use 400 when the request is malformed (bad JSON syntax, missing required fields). Use 422 when the request is syntactically valid but semantically wrong (email format is valid but the domain does not exist). Many APIs use 400 for everything, which works but is less precise.

401 vs 403

401 means "I do not know who you are." The client should authenticate and retry. 403 means "I know who you are and you are not allowed." Retrying with the same credentials will not help. Getting this distinction right improves client-side error handling.

Rate Limiting

Use 429 Too Many Requests with a Retry-After header. Include rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) in every response so clients can throttle proactively.

Error Response Format

Always return a JSON body with error details, even for 4xx and 5xx responses. Include a machine-readable error code, a human-readable message, and optionally a link to documentation. Use our HTTP Status Code Lookup tool to reference the full list while designing your API.