HTTP Status Codes Reference Guide
Stop returning 200 OK with error messages inside the body. Here is the authoritative guide to choosing the correct HTTP status code for modern REST APIs.
HTTP Status Codes & Method Matrix
Quick-lookup reference with RFC standards and prescriptive production guidelines for REST engineers.
The standard response for successful HTTP requests with an entity body.
Return with payload on successful GET, PUT, or PATCH calls.
The request has succeeded and led to the creation of a new resource.
Always include a 'Location' header pointing to the newly created URI on POST.
The server has fulfilled the request and there is no additional content to send in the payload body.
Standard for successful DELETE or PUT operations when no body is returned.
Indicates that the resource has not been modified since the version specified by the conditional request headers (If-None-Match / ETag).
Critical for client and CDN caching efficiency; must omit payload body.
The server cannot or will not process the request due to perceived client syntax error (malformed JSON, invalid query param types).
Use for structural/syntax parsing failures. For semantic validation, prefer 422.
Although the HTTP standard specifies 'unauthorized', semantically this means unauthenticated.
The client must authenticate itself. Always provide a WWW-Authenticate header.
The client's identity is known, but the client does not have access permissions for the requested resource.
Authentication will not help. Use for Role-Based Access Control (RBAC) rejection.
The origin server did not find a current representation for the target resource.
Return RFC 9457 Problem Details. Never return 200 OK with null.
The request could not be completed due to a conflict with the current state of the target resource.
Ideal for optimistic locking failures or unique constraint collisions (e.g. email exists).
The server understands the content type and syntax, but was unable to process the contained instructions.
Industry gold-standard for schema and business validation errors.
The user has sent too many requests in a given amount of time ('rate limiting').
Always include 'Retry-After' (in seconds) and rate-limit remaining headers.
The server encountered an unexpected condition that prevented it from fulfilling the request.
Log the stack trace internally, return an opaque correlation/trace ID to the client.
The server is currently unable to handle the request due to a temporary overload or scheduled maintenance.
Supply a 'Retry-After' header to guide automated client retry mechanisms.
HTTP Methods: Safety & Idempotency Matrix
Crucial for distributed retry logic and AI agent tool calling.
| Method | Safe? | Idempotent? | Cacheable? | Standard Semantics |
|---|---|---|---|---|
| GET | Yes (Read-only) | Yes | Yes | Retrieve a resource representation |
| POST | No | No (Requires Idempotency-Key) | Only with explicit headers | Process entity / create subordinate resource |
| PUT | No | Yes | No | Complete replacement of the target resource |
| PATCH | No | Depends (Generally No) | No | Partial modification (RFC 7396 Merge Patch) |
| DELETE | No | Yes | No | Relinquish resource representation |
Problem Details for HTTP APIs (RFC 9457)
RFC 9457 replaces RFC 7807 to define a standard JSON media type (application/problem+json) for carrying machine-readable details of errors in HTTP response bodies.
// HTTP/1.1 422 Unprocessable Content Content-Type: application/problem+json { "type": "https://api.buildrestapi.com/errors/invalid-credentials", "title": "Validation Error", "status": 422, "detail": "The password supplied does not meet entropy requirements.", "instance": "/v1/users/create", "invalid_params": [ { "name": "password", "reason": "Must contain at least 12 characters and a symbol" } ] }