HTTP Status Codes: Full List with REST API Usage
Every HTTP response status code in one searchable list, from 100 Continue to 511, with notes on when your REST API should return each one. Look up a response status code you just got back, or decide which API status code to send for a bad request, a resource that already exists, or a successful create.
Runs in your browser — nothing is uploaded.Search and filters work offline once the page has loaded.
62 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.
Early Hints
Sent before the final response so the browser can start preloading resources listed in Link headers.
REST API context
A performance feature for HTML pages (preload CSS/fonts while the server is still rendering). Not used in JSON APIs.
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.
Non-Authoritative Information
The request succeeded, but the returned content was modified by a transforming proxy.
REST API context
Set by proxies, not by your API. You will rarely see it.
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.
Reset Content
The request succeeded and the client should reset the document view, e.g. clear a form.
REST API context
Rare in REST. Like 204, it must not include a 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.
Already Reported
Members of a DAV binding were already listed in a previous part of a 207 response.
REST API context
WebDAV only. Avoid in REST APIs.
IM Used
The server fulfilled a GET with one or more instance manipulations (delta encoding) applied.
REST API context
Delta encoding (RFC 3229). Practically unused.
Multiple Choices
The request has more than one possible response and the client should choose one.
REST API context
Content negotiation without a clear winner. Almost never used by APIs.
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.
See Other
The response can be found at another URI using GET.
REST API context
The standard Post/Redirect/Get pattern: after a POST, redirect the client to the result with a GET. Also used to point to the status URL of an async job.
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.
Use Proxy
Deprecated. The resource must be accessed through the proxy in the Location header.
REST API context
Deprecated for security reasons. Browsers ignore it — never send it.
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.
Not Acceptable
The server cannot produce a response matching the Accept headers sent by the client.
REST API context
Client asked for Accept: application/xml from a JSON-only API. Many APIs ignore Accept and just return JSON instead.
Proxy Authentication Required
Like 401, but authentication is required by a proxy between the client and the server.
REST API context
Comes from corporate proxies, not from your API. Check HTTP(S)_PROXY credentials in CI environments.
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.
Length Required
The server requires a Content-Length header.
REST API context
Some servers and gateways reject POST/PUT bodies sent without Content-Length (e.g. chunked uploads).
Precondition Failed
A precondition in the request headers (If-Match, If-Unmodified-Since) evaluated to false.
REST API context
Optimistic concurrency: the client sent If-Match with an old ETag, so someone else changed the resource first. Client should re-fetch and retry.
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.
URI Too Long
The request URI is longer than the server is willing to interpret.
REST API context
Usually huge query strings. Move filters into a POST body (e.g. a /search endpoint).
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.
Range Not Satisfiable
The Range header asks for a part of the resource that doesn't exist.
REST API context
Resumable downloads asking past the end of the file. Return Content-Range: bytes */<size>.
Expectation Failed
The server cannot meet the requirements of the Expect request header.
REST API context
Usually a server or proxy that doesn't support Expect: 100-continue.
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.
Misdirected Request
The request was sent to a server that cannot produce a response for this scheme and authority.
REST API context
Seen with HTTP/2 connection reuse across hostnames that share a certificate but not a backend.
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.
Locked
The resource being accessed is locked.
REST API context
WebDAV. Some APIs use it for records locked by another user or process.
Failed Dependency
The request failed because it depended on another request that failed.
REST API context
WebDAV. Occasionally used in batch APIs when one step's failure aborts the next.
Too Early
The server is unwilling to process a request that might be replayed (TLS 1.3 early data).
REST API context
Protects non-idempotent requests sent as 0-RTT early data. Clients should retry after the handshake.
Upgrade Required
The server refuses the request using the current protocol and requires an upgrade.
REST API context
Include an Upgrade header naming the required protocol.
Precondition Required
The server requires the request to be conditional (If-Match).
REST API context
Forces clients to send an ETag on updates so they can't overwrite each other's changes blindly (lost-update protection).
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.
Request Header Fields Too Large
The server refuses the request because its headers are too large.
REST API context
Very often oversized cookies or a huge JWT in the Authorization header. Trim cookies or move data out of the token.
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.
HTTP Version Not Supported
The server does not support the HTTP version used in the request.
REST API context
Rare; comes from misconfigured clients or proxies.
Variant Also Negotiates
Content negotiation configuration error on the server (circular reference).
REST API context
Server misconfiguration. You will almost never see it.
Insufficient Storage
The server cannot store the representation needed to complete the request.
REST API context
WebDAV origin, but reasonable for 'disk full' or storage quota errors on upload endpoints.
Loop Detected
The server detected an infinite loop while processing the request.
REST API context
WebDAV. Some CDNs and proxies return it for redirect or proxy loops.
Not Extended
Further extensions to the request are required (RFC 2774).
REST API context
Obsoleted — the extension framework it belongs to was never adopted.
Network Authentication Required
The client needs to authenticate to gain network access.
REST API context
Captive portals (hotel or airport Wi-Fi). If your API client sees it, the network — not your API — is blocking the request.
The five classes of HTTP status codes
The first digit tells you who is responsible and whether retrying makes sense:
| Class | Meaning | In practice |
|---|---|---|
| 1xx | Informational | Interim responses. 100 Continue, 101 Switching Protocols (WebSocket upgrade), 103 Early Hints. You rarely send these by hand. |
| 2xx | Success | The request was received, understood and accepted. 200, 201, 202, 204. |
| 3xx | Redirection | The client must take another step, usually follow the Location header. 301, 302, 304, 307, 308. |
| 4xx | Client error | The request is wrong and retrying it unchanged won't help. 400, 401, 403, 404, 409, 422, 429. |
| 5xx | Server error | The request may be fine; the server or something behind it failed. Retrying later may work. 500, 502, 503, 504. |
Which status code should my REST API return?
Find your situation in the left column. These are the REST API response codes that well-designed public APIs (GitHub, Stripe, Google) converge on:
| Situation | Status code | Also send |
|---|---|---|
| GET returned the resource | 200 OK | Body contains the resource. |
| POST created something | 201 Created | Add Location: /items/42 and return the new item. |
| Job queued, not finished | 202 Accepted | Return a URL where the client can poll for status. |
| DELETE succeeded | 204 No Content | No body at all. |
| Malformed JSON / missing parameter | 400 Bad Request | Say what's wrong: which field, which line. |
| Valid JSON, invalid values | 422 Unprocessable Content | Return per-field validation errors. |
| No token, or token expired | 401 Unauthorized | Include a WWW-Authenticate header. |
| Logged in but not allowed | 403 Forbidden | Or 404 if the resource's existence is itself secret. |
| ID doesn't exist | 404 Not Found | Same for unknown routes. |
| Wrong HTTP method on a route | 405 Method Not Allowed | Include Allow: GET, POST. |
| Resource already exists / edit conflict | 409 Conflict | Duplicate email, ETag mismatch, state machine violation. |
| Unsupported body type | 415 Unsupported Media Type | Client sent XML or form data to a JSON-only endpoint. |
| Rate limit hit | 429 Too Many Requests | Include Retry-After. |
| Unhandled exception | 500 Internal Server Error | Log the details, return a generic message. |
| Down for maintenance / overloaded | 503 Service Unavailable | Include Retry-After if you know it. |
Return a useful error body, not just a code
The status code tells a client what kind of failure happened; the body should say what exactly. RFC 9457 (Problem Details for HTTP APIs) defines a standard shape with the media type application/problem+json. A duplicate-email signup would look like this:
HTTP/1.1 409 Conflict
Content-Type: application/problem+json
{
"type": "https://api.example.com/problems/email-taken",
"title": "Email already registered",
"status": 409,
"detail": "An account with ada@example.com already exists.",
"instance": "/users"
}Common status code mistakes
- 200 for everything. A
200 OKwith{"error": "not found"}is invisible to monitoring, caches and retry logic. - 500 for validation errors. If the client sent bad input, it's a 4xx. Reserve 5xx for failures the client can't fix — otherwise your error-rate alerts fire for user typos.
- 401 when you mean 403. 401 says "log in"; a logged-in user who lacks a role should get 403, or a client will loop through re-authentication.
- 302 for API redirects. Clients may turn a redirected POST into a GET. Use 307 (temporary) or 308 (permanent) to keep the method and body.
- 404 for a resource that was deleted on purpose. 410 Gone tells crawlers and clients it won't come back.
For the reasoning behind each choice, with request/response examples, read the REST API status codes guide and the REST API best practices article.
Most Common HTTP Status Codes
Quick reference for the codes you'll use and debug most often in REST APIs:
| Code | Name | When to use |
|---|---|---|
| 200 | OK | Request succeeded. Use for GET, PUT, PATCH that return a body. |
| 201 | Created | POST that created a new resource. Include Location header with the new resource URL. |
| 204 | No Content | Success but no response body — typically DELETE or PUT when not returning the updated resource. |
| 301 | Moved Permanently | Resource has permanently moved. Browsers and bots follow and cache the redirect. |
| 304 | Not Modified | Conditional GET: the cached copy is still valid (ETag / If-None-Match matched). No body. |
| 400 | Bad Request | Malformed request — invalid JSON, missing required fields at the protocol level. |
| 401 | Unauthorized | Not authenticated. The client needs to log in or provide a valid token. |
| 403 | Forbidden | Authenticated but not authorized. You know who they are but they can't access this. |
| 404 | Not Found | Resource doesn't exist (or you're hiding it intentionally to avoid exposing existence). |
| 409 | Conflict | Valid request but conflicts with current state — duplicate email, concurrent edit collision. |
| 422 | Unprocessable Content | Valid JSON but semantically wrong — invalid date value, negative price, etc. |
| 429 | Too Many Requests | Rate limit exceeded. Include Retry-After header. |
| 500 | Internal Server Error | Unhandled server error. Log it, fix it, don't expose internal details to the client. |
| 502 | Bad Gateway | Upstream service returned an invalid response — common in nginx → app server setups. |
| 503 | Service Unavailable | Server temporarily down — maintenance, overload. Include Retry-After if known. |
| 504 | Gateway Timeout | The proxy gave up waiting for the upstream — often a slow query or a hung worker. |
Status code guides: causes and fixes
One page per code you're most likely to debug, with the RFC definition, common causes, nginx, Express and Next.js fixes, the headers that matter and how it affects SEO.
200OK
201Created
204No Content
301Moved Permanently
302Found
304Not Modified
307Temporary Redirect
308Permanent Redirect
400Bad Request
401Unauthorized
403Forbidden
404Not Found
405Method Not Allowed
409Conflict
413Content Too Large
422Unprocessable Content
429Too Many Requests
500Internal Server Error
502Bad Gateway
503Service Unavailable
504Gateway Timeout
Learn more
HTTP Status Codes for REST APIs: 200 vs 201 vs 204, 400 vs 422 vs 429
A practical guide to choosing the right HTTP status code in REST API design. Covers the most confusing pairs: 200 vs 201, 400 vs 422, 401 vs 403, and when to use 503 vs 429.
REST API Design Best Practices: A Practical Guide
The conventions that make REST APIs intuitive and consistent. Covers URL design, HTTP methods, status codes, versioning, pagination, and error responses.
CORS Explained: Why It Happens and How to Fix It
CORS errors happen when a browser blocks a request to a different origin. Learn how the Same-Origin Policy works, what preflight requests are, and how to configure CORS correctly in Express, FastAPI, and Nginx.
Related Tools
Frequently Asked Questions
Which HTTP status code indicates a successful request?▾
Any code in the 2xx range means success. The three you will use most in a REST API are 200 OK (success with a response body — typical for GET, PUT and PATCH), 201 Created (a POST created a new resource; add a Location header pointing to it) and 204 No Content (success with no body — typical for DELETE). 202 Accepted means the request was accepted for asynchronous processing but is not finished yet.
What is the status code for a bad request?▾
400 Bad Request. Use it when the server cannot or will not process the request because of a client error: malformed JSON, a wrong Content-Type, a missing required query parameter or an invalid header. If the body parses fine but the values are invalid (a negative quantity, an end date before the start date), many APIs use 422 Unprocessable Content instead so clients can tell syntax errors from validation errors. Either way, return a body that says which field is wrong.
What status code should an API return when a resource already exists?▾
409 Conflict. It means the request is valid but conflicts with the current state of the server — the classic example is POST /users with an email that is already registered, or creating a resource with an ID that is taken. Some APIs return 422 for duplicates because they treat uniqueness as a validation rule; that is acceptable if you are consistent. Avoid 400 (too vague) and never 500 (the server did not fail). Be careful on signup and password-reset endpoints: a 409 there reveals which emails have accounts.
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 an API return 200 OK with an error message in the body?▾
No. Returning 200 with { "success": false } breaks every client, proxy, monitoring tool and retry library that relies on the status code — they will all treat the failure as a success. Use the 4xx or 5xx code that matches the problem and put the details in the body, ideally in the RFC 9457 Problem Details format (application/problem+json). GraphQL is the well-known exception: it often returns 200 with an errors array by design.
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 is the difference between 502, 503 and 504?▾
All three usually come from a proxy, load balancer or gateway in front of your app rather than from the app itself. 502 Bad Gateway: the upstream server returned an invalid response or closed the connection (the app crashed, or is listening on the wrong port). 503 Service Unavailable: the server is temporarily unable to handle requests — overloaded, in maintenance, or no healthy instances; add Retry-After if you know when it will be back. 504 Gateway Timeout: the upstream did not answer within the proxy's timeout, often a slow database query.
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.