http
HTTP/1.1 200 OKNotes
Use `200 OK` for successful reads and updates when you are returning a representation.
REST API Status Codes and Error Response Design
Practical HTTP status codes, error response bodies, validation failures, and troubleshooting-friendly API error contracts.
Export
Copy the compact sheet, download it, or print it.
Download
`D` dense toggle · `C` copy all
Success status codes
Return the narrowest success code that matches the outcome.
http
HTTP/1.1 201 Created
Location: /users/usr_123Notes
`201 Created` is ideal when a new resource has been created and you can identify its URL.
http
HTTP/1.1 202 AcceptedNotes
Use this when the work has started or been queued but is not finished yet.
http
HTTP/1.1 204 No ContentNotes
Common for deletes and some updates where the client does not need a representation back.
http
HTTP/1.1 304 Not ModifiedNotes
Useful with ETag or Last-Modified validators for efficient client caching.
Client and server errors
Distinguish invalid input, missing auth, conflicts, and server failures.
http
HTTP/1.1 400 Bad RequestNotes
Use 400 when the request cannot be understood or parsed as sent.
http
HTTP/1.1 401 Unauthorized
WWW-Authenticate: BearerNotes
401 means the client needs valid authentication. It is not the same as lacking permission.
http
HTTP/1.1 403 ForbiddenNotes
Return 403 when the identity is known but access is denied.
http
HTTP/1.1 404 Not FoundNotes
Use 404 when the targeted resource cannot be found or should not be disclosed.
http
HTTP/1.1 409 ConflictNotes
Common for uniqueness violations, version conflicts, and invalid state transitions.
http
HTTP/1.1 412 Precondition FailedNotes
A strong fit when using conditional requests such as `If-Match` with ETags.
422 Unprocessable Content
Well-formed request but semantic validation failed.
httpANYhttp422validation
http
HTTP/1.1 422 Unprocessable ContentNotes
Use 422 when the JSON shape is valid but business validation rules are not satisfied.
http
HTTP/1.1 429 Too Many Requests
Retry-After: 60Notes
Useful for API abuse protection and fair usage enforcement.
http
HTTP/1.1 500 Internal Server ErrorNotes
Reserve 500 for unhandled errors or unknown failures; do not use it for predictable validation problems.
Error response body
Return structured error details clients can act on.
json
{
"error": {
"code": "EMAIL_ALREADY_EXISTS",
"message": "An account with that email already exists.",
"details": {
"field": "email"
},
"request_id": "req_01HXYZ..."
}
}Notes
Machine-readable codes plus a human-readable message help both client UX and support troubleshooting.
json
{
"error": {
"code": "VALIDATION_FAILED",
"message": "One or more fields are invalid.",
"fields": [
{ "name": "email", "code": "INVALID_FORMAT" },
{ "name": "password", "code": "TOO_SHORT" }
]
}
}Notes
Returning all field failures reduces trial-and-error for API consumers and form builders.
More in REST API
REST API Best Practices and Anti-Patterns
High-signal design rules, consistency patterns, and common mistakes to avoid in production APIs.
REST API Request and Response Patterns
JSON request bodies, envelope choices, sparse fieldsets, includes, concurrency control, and common response contracts.
REST API Authentication, Authorization, and Versioning
Bearer auth, API keys, permission errors, versioning strategies, and compatibility patterns for HTTP APIs.
REST API Pagination, Filtering, Sorting, and Search
Common collection query patterns including offset pagination, cursor pagination, filtering, sorting, and search.
REST API Resource Naming and URL Design
Naming conventions for resources, relationships, nested endpoints, and clean URL design.
REST API Methods and Idempotency
HTTP methods, safe vs unsafe semantics, and idempotency examples for API consumers and designers.