HTTP Status Codes
A searchable reference of all HTTP status codes with descriptions and REST API context — including when to use each code in your API design. Filter by category or search by code number or name.
34 status codes
Continue
The server has received the request headers and the client should proceed to send the request body.
REST API context
Rarely used in REST APIs. Used before sending a large body to verify the server accepts it — avoids wasted bandwidth.
Switching Protocols
The server agrees to switch protocols as requested by the client via the Upgrade header.
REST API context
Used when upgrading an HTTP connection to WebSocket. Your REST framework handles this automatically.
Processing
The server has received and is processing the request, but no response is available yet.
REST API context
WebDAV extension. In REST, prefer 202 Accepted for long-running operations instead.
OK
The request succeeded. The meaning depends on the HTTP method.
REST API context
Default success for GET, PUT, PATCH. Return the requested or updated resource in the response body.
Created
The request succeeded and a new resource was created as a result.
REST API context
Use for successful POST that creates a resource. Include a Location header with the URL of the new resource.
Accepted
The request has been accepted for processing but processing is not complete.
REST API context
Use for async operations (queued jobs, background tasks). Return a job ID or status URL the client can poll.
No Content
The server successfully processed the request and is not returning any content.
REST API context
Use for successful DELETE, or PUT/PATCH when you don't need to return the updated resource. No response body.
Partial Content
The server is delivering only part of the resource due to a Range header sent by the client.
REST API context
Used for resumable file downloads and streaming media. Requires Content-Range header in the response.
Multi-Status
The response body contains multiple status codes for multiple independent operations.
REST API context
WebDAV. Useful in REST batch APIs — returns individual status per item in a bulk request.
Moved Permanently
The URL of the requested resource has been changed permanently to the URL given in the Location header.
REST API context
Use when an API endpoint is permanently renamed. Clients and search engines should update their links.
Found
The URI of the requested resource has been changed temporarily.
REST API context
Temporary redirect. Clients should continue using the original URI for future requests. Rarely needed in REST.
Not Modified
The resource has not been modified since the version specified by the If-None-Match or If-Modified-Since headers.
REST API context
Enables HTTP caching. Return this when the client's cached version is still current — saves bandwidth.
Temporary Redirect
The request should be repeated with another URI using the same method.
REST API context
Like 302 but guarantees the HTTP method is preserved. Use when a POST must stay a POST after redirect.
Permanent Redirect
The request and all future requests should be directed to the given URI.
REST API context
Like 301 but preserves the HTTP method. Preferred for permanent API endpoint migrations.
Bad Request
The server cannot process the request due to a client error — malformed syntax, invalid framing, or deceptive request routing.
REST API context
Use for malformed JSON, missing required fields, or invalid parameter types. Return field-level validation errors in the body.
Unauthorized
Authentication is required and has failed or has not yet been provided.
REST API context
Missing or invalid auth credentials. Must include a WWW-Authenticate header. Use 403 if the user IS authenticated but lacks permission.
Payment Required
Reserved for future use, now used by some APIs to indicate a payment is required.
REST API context
Used by SaaS APIs to indicate a free tier limit has been exceeded or subscription is required.
Forbidden
The server understood the request but refuses to authorize it.
REST API context
Authenticated user lacks permission. Don't reveal whether the resource exists — return 404 if exposing existence is a risk.
Not Found
The server cannot find the requested resource.
REST API context
Resource doesn't exist. Also use to hide existence of resources the authenticated user can't access (security through obscurity).
Method Not Allowed
The request method is known but not supported for the target resource.
REST API context
Must include an Allow header listing supported methods. E.g., DELETE /users returns 405 with Allow: GET, POST.
Request Timeout
The server timed out waiting for the request.
REST API context
Rare in REST — most timeouts happen at the infrastructure level. Consider 503 for server-side resource exhaustion.
Conflict
The request could not be completed due to a conflict with the current state of the target resource.
REST API context
Use when creating a duplicate resource, or for optimistic locking failures (ETag mismatch). Return conflict details in body.
Gone
The target resource is no longer available and will not be available again.
REST API context
Use instead of 404 when a resource existed but was permanently deleted. Signals clients to remove cached references.
Content Too Large
The request entity is larger than limits defined by the server.
REST API context
File upload too large. Include the maximum allowed size in the response body or a custom header.
Unsupported Media Type
The server refuses the request because the media type is not supported.
REST API context
Client sent wrong Content-Type (e.g., text/plain instead of application/json). Specify accepted types in the error response.
I'm a Teapot
The server refuses the attempt to brew coffee with a teapot.
REST API context
An April Fools' joke from RFC 2324 (1998). Not for real use — but some APIs use it for easter eggs or to reject obviously bad requests.
Unprocessable Content
The server understands the content type and the request entity is syntactically correct but semantically wrong.
REST API context
Preferred over 400 for semantic validation errors — valid JSON structure but invalid business logic. Return field-level errors.
Too Many Requests
The user has sent too many requests in a given amount of time (rate limiting).
REST API context
Always include Retry-After header. Consider X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset headers.
Unavailable For Legal Reasons
The user agent requested a resource that cannot legally be provided.
REST API context
Content blocked by legal order (copyright, GDPR, government censorship). Named after Fahrenheit 451 by Ray Bradbury.
Internal Server Error
The server encountered an unexpected condition that prevented it from fulfilling the request.
REST API context
Generic server error. Never expose stack traces or internal details. Log server-side; return a correlation ID to the client.
Not Implemented
The server does not support the functionality required to fulfill the request.
REST API context
Use for HTTP methods your server doesn't implement at all. Different from 405 which means 'not allowed on this resource'.
Bad Gateway
The server, acting as a gateway, received an invalid response from an upstream server.
REST API context
Upstream microservice or dependency returned an unexpected response. Implement retry with exponential backoff on clients.
Service Unavailable
The server is not ready to handle the request — overloaded or down for maintenance.
REST API context
Planned downtime or resource exhaustion. Include Retry-After header when recovery time is known. Use in health checks.
Gateway Timeout
The server, acting as a gateway, did not receive a timely response from an upstream server.
REST API context
Upstream service is too slow. Log which service timed out. Clients should implement retry with backoff and circuit breaker.
Related Tools
Frequently Asked Questions
What is the difference between 400, 422, and 409?▾
400 Bad Request is for requests that are structurally broken — malformed JSON, wrong Content-Type, missing required fields at the protocol level. 422 Unprocessable Content is for requests that are structurally valid (parseable JSON) but semantically invalid — a valid JSON body where a date field contains an invalid date, or a price is negative. 409 Conflict means the request is valid but conflicts with the current state of the resource — creating a user with an email that already exists, or a concurrent edit collision (ETag mismatch).
What is the difference between 401 Unauthorized and 403 Forbidden?▾
401 means the request lacks valid authentication credentials — the user is not logged in, their token is expired, or the credentials are wrong. The server is saying 'I don't know who you are; please authenticate.' 403 means the server knows who you are (authentication succeeded) but you don't have permission to access this resource. A common mistake is returning 401 when you mean 403, or returning 403 when you should return 404 (to avoid revealing the existence of a resource).
Should I use 200 or 201 when creating a resource?▾
Use 201 Created when a POST request successfully creates a new resource. Include a Location response header with the URI of the newly created resource (e.g., Location: /users/123). Use 200 OK for GET, PUT, and PATCH that succeed and return a response body. Using 200 for creation is technically incorrect per the HTTP spec, though many APIs do it. The spec difference matters for caching and for clients that want to distinguish 'updated' from 'created'.
When should I use 204 No Content vs 200 OK?▾
204 No Content is for successful requests where there is intentionally no response body — the most common case is DELETE. It tells the client 'it worked, nothing to return.' Also use 204 for PUT/PATCH when you've processed the update but don't want to return the updated resource. Use 200 OK when you're returning a body (the updated resource, a confirmation object, etc.). Never send a body with a 204 response — clients and HTTP frameworks may discard it.
What headers should I include with a 429 Too Many Requests response?▾
At minimum, include Retry-After to tell clients when they can try again (value is either a number of seconds or an HTTP-date). For more transparency, add: X-RateLimit-Limit (total requests allowed in the window), X-RateLimit-Remaining (requests remaining), and X-RateLimit-Reset (Unix timestamp when the window resets). These headers let clients implement respectful retry logic and display accurate rate limit feedback to users.