HTTP status codes list
HTTP status codes are three-digit numbers a server sends with every response: 2xx means it worked, 3xx means look elsewhere, 4xx means the request was wrong and 5xx means the server failed.
62 codes
1xx Informational
[100]Continue
The server got the request headers and the client should go ahead and send the body.
Send it when Rarely by hand. Web servers send it when a client asks with Expect: 100-continue before a large upload.
[101]Switching Protocols
The server agrees to switch to the protocol the client asked for in the Upgrade header.
Send it when When accepting a WebSocket upgrade. Your WebSocket library sends it for you.
[102]Processing
The server accepted the request and is still working on it (WebDAV).
Send it when Almost never. Use 202 Accepted for slow work instead.
[103]Early Hints
The server sends Link headers early so the browser can preload assets while the real response is prepared.
Send it when When you know the CSS and scripts a page needs before the page itself is ready.
2xx Success
[200]OK
The request worked and the response carries the result.
Send it when For a successful GET, or a PUT or PATCH that returns the updated resource.
[201]Created
The request worked and a new resource now exists.
Send it when After a POST that creates something. Add a Location header pointing at the new resource.
Next to Use 200 when nothing new was created.
[202]Accepted
The request was accepted for processing, but the work is not finished.
Send it when For queued or background jobs. Return a job id or status URL the client can poll.
Next to 201 means it exists now, 202 means it will later.
[203]Non-Authoritative Information
The request worked but a proxy changed the response from the origin.
Send it when Proxies only. Apps almost never send it.
[204]No Content
The request worked and there is intentionally no body.
Send it when For a DELETE, or a PUT or PATCH where the client needs nothing back.
Next to Do not send a body with a 204.
[205]Reset Content
The request worked and the client should reset the form or view that sent it.
Send it when Rare. Some form flows use it to clear the form.
[206]Partial Content
The server is returning only the byte range the client asked for.
Send it when For Range requests, such as video seeking and resumable downloads. Include Content-Range.
[207]Multi-Status
The body holds separate status codes for several sub-operations (WebDAV).
Send it when For batch endpoints where some items succeed and others fail, if you accept the WebDAV style body.
[208]Already Reported
Members of a WebDAV binding were already listed earlier in the response.
Send it when WebDAV only.
[226]IM Used
The response is the result of applying instance manipulations (delta encoding) to the current resource.
Send it when Almost never.
3xx Redirection
[300]Multiple Choices
There are several possible responses and the client should pick one.
Send it when Rarely. Content negotiation usually picks for the client.
[301]Moved Permanently
The URL has a new permanent address. Clients and search engines should update their links.
Send it when For permanent URL changes, such as http to https or a renamed page. Include Location.
Next to Browsers may turn a POST into a GET after a 301. Use 308 to keep the method.
[302]Found
The resource is temporarily at another URL. Keep using the original URL.
Send it when For a temporary redirect, such as sending a logged-out user to a login page.
Next to Many clients switch POST to GET. Use 307 to keep the method.
[303]See Other
The result is at another URL and the client should fetch it with GET.
Send it when After a POST form submit, to redirect to a result page so a refresh does not resubmit.
[304]Not Modified
The cached copy is still good. There is no body.
Send it when When a conditional request (If-None-Match or If-Modified-Since) matches the current version.
[305]Use Proxy
Deprecated. Once meant the resource must be accessed through a proxy.
Send it when Never. Browsers ignore it.
[307]Temporary Redirect
Temporary redirect that keeps the request method and body.
Send it when When a POST or PUT must be repeated at another URL for now.
Next to 302 may change the method, 307 never does.
[308]Permanent Redirect
Permanent redirect that keeps the request method and body.
Send it when For permanent moves of endpoints that take POST or PUT, such as an API path rename.
Next to 301 may change the method, 308 never does.
4xx Client error
[400]Bad Request
The server cannot understand the request: broken syntax, malformed JSON, a missing header or an invalid parameter.
Send it when When the request itself is malformed, such as JSON that does not parse, a broken header or a query parameter that is not the right type.
Next to If the JSON parses but the values break your rules, 422 is more precise.
Fix the request before retrying
[401]Unauthorized
The request has no valid credentials. Despite the name, this means unauthenticated.
Send it when When the token or session is missing, expired or invalid. Include WWW-Authenticate.
Next to 401 means we do not know who you are. 403 means we know and the answer is no.
Fix the request before retrying
[402]Payment Required
Reserved for payment flows. Some APIs use it when an account owes money or is out of credit.
Send it when When a paid feature is blocked because of billing, if your clients expect it.
Fix the request before retrying
[403]Forbidden
The server knows who you are and refuses to allow this action.
Send it when When a signed-in user lacks permission, such as a member deleting an admin only resource.
Next to Sending credentials again will not help, unlike 401.
Retrying the same request will not help
[404]Not Found
There is nothing at this URL, or the server will not say whether there is.
Send it when When the route or record does not exist. Also fine for records the caller may not know exist.
Next to If it used to exist and is gone for good, 410 says so.
Retrying the same request will not help
[405]Method Not Allowed
The URL exists but not for this HTTP method.
Send it when When a route is hit with the wrong verb, such as GET on a POST only endpoint. Include Allow.
Fix the request before retrying
[406]Not Acceptable
The server cannot produce a response that matches the client Accept headers.
Send it when When the client asks only for a format you cannot return.
Fix the request before retrying
[407]Proxy Authentication Required
Like 401, but the credentials are needed by a proxy.
Send it when Proxies only.
Fix the request before retrying
[408]Request Timeout
The server gave up waiting for the client to finish sending the request.
Send it when When a client opens a connection and then sends too slowly. Servers often send it on their own.
Retrying the same request can work
[409]Conflict
The request conflicts with the current state of the resource.
Send it when For duplicate unique values, edit collisions and invalid state changes, such as cancelling a shipped order.
Next to Use 422 when the data is invalid on its own, 409 when it clashes with what already exists.
Fix the request before retrying
[410]Gone
The resource used to exist and was removed on purpose, with no forwarding address.
Send it when For deleted content you want search engines to drop faster than a 404.
Retrying the same request will not help
[411]Length Required
The server needs a Content-Length header.
Send it when When a request body arrives without a length and you cannot accept chunked bodies.
Fix the request before retrying
[412]Precondition Failed
A condition in the request headers, such as If-Match, was false.
Send it when For optimistic locking: the client edits a version that is no longer current.
Fix the request before retrying
[413]Content Too Large
The request body is bigger than the server allows. Formerly called Payload Too Large.
Send it when When an upload or JSON body exceeds your limit. State the limit in the error body.
Fix the request before retrying
[414]URI Too Long
The URL is longer than the server will process.
Send it when When a query string is too long. Move the data into a POST body.
Fix the request before retrying
[415]Unsupported Media Type
The server does not accept the format of the request body.
Send it when When Content-Type is something you cannot parse, such as text/plain sent to a JSON only endpoint.
Fix the request before retrying
[416]Range Not Satisfiable
The requested byte range does not fit the resource.
Send it when When a Range header points past the end of the file. Include Content-Range with the real size.
Fix the request before retrying
[417]Expectation Failed
The server cannot meet the Expect header requirement.
Send it when Rarely. Mostly proxies reject Expect: 100-continue this way.
Fix the request before retrying
[418]I'm a teapot
A joke code from an April Fools RFC. The teapot refuses to brew coffee.
Send it when Only as a joke. A few sites return it to bots and scanners they want to turn away.
[421]Misdirected Request
The request reached a server that cannot answer for that host, often a TLS or HTTP/2 connection reuse problem.
Send it when Rarely from apps. Proxies and CDNs send it.
Retrying the same request can work
[422]Unprocessable Content
The request is well formed but the values fail validation. Formerly called Unprocessable Entity.
Send it when For validation errors on parsed data: bad email format, a date in the past, a missing required field. List each field error in the body.
Next to 400 is for requests the server cannot parse, 422 for requests it parsed and rejected.
Fix the request before retrying
[423]Locked
The resource is locked (WebDAV).
Send it when When another user or process holds a lock on the record.
Retrying the same request can work
[424]Failed Dependency
The request failed because an earlier request it depended on failed (WebDAV).
Send it when In multi-step batches when a previous step failed.
Fix the request before retrying
[425]Too Early
The server will not process a request that could be replayed, such as TLS early data.
Send it when Rarely from apps.
Retrying the same request can work
[426]Upgrade Required
The client must switch to another protocol or protocol version.
Send it when When you refuse plain HTTP or an old protocol. Include the Upgrade header.
Fix the request before retrying
[428]Precondition Required
The server requires the request to be conditional.
Send it when To force clients to send If-Match so they do not overwrite changes by accident.
Fix the request before retrying
[429]Too Many Requests
The client is rate limited.
Send it when When a caller exceeds your rate limit. Add a Retry-After header.
Next to 503 means the server is overloaded for everyone, 429 means this client sent too much.
Retrying the same request can work
[431]Request Header Fields Too Large
A header, or all headers together, is too big.
Send it when When cookies or a header grow past your limit. Usually a web server sends it.
Fix the request before retrying
[451]Unavailable For Legal Reasons
The content is blocked because of a legal demand.
Send it when When a court order, takedown or regional law requires blocking the content.
Retrying the same request will not help
5xx Server error
[500]Internal Server Error
The server hit an unexpected problem and could not finish the request.
Send it when For unhandled exceptions. Log the stack trace on the server and keep details out of the response body.
Next to This is the code your error tracker should see most. A 5xx on a known case, such as a failed dependency, deserves a more specific code.
Retrying the same request can work
[501]Not Implemented
The server does not support the method or feature the request needs.
Send it when For HTTP methods or features you do not support at all.
Retrying the same request will not help
[502]Bad Gateway
A gateway or proxy got an invalid response from the server behind it.
Send it when Proxies, load balancers and API gateways send it when the upstream app crashed or sent garbage.
Next to 502 is an invalid answer, 504 is no answer in time.
Retrying the same request can work
[503]Service Unavailable
The server cannot take requests right now, usually from overload or maintenance.
Send it when During maintenance windows or load shedding. Add Retry-After.
Retrying the same request can work
[504]Gateway Timeout
A gateway or proxy did not get a response from the upstream server in time.
Send it when Proxies send it when your app is too slow. Fix the slow request, or raise the proxy timeout.
Retrying the same request can work
[505]HTTP Version Not Supported
The server does not support the HTTP version of the request.
Send it when Almost never.
Retrying the same request will not help
[506]Variant Also Negotiates
A content negotiation setup refers to itself in a loop.
Send it when Almost never.
Retrying the same request will not help
[507]Insufficient Storage
The server has no room to store what the request needs (WebDAV).
Send it when When disk or quota is full on the server side.
Retrying the same request can work
[508]Loop Detected
The server found an infinite loop while processing the request (WebDAV).
Send it when When a recursive structure cannot be resolved.
Retrying the same request will not help
[510]Not Extended
The request needs further extensions the server does not have.
Send it when Almost never.
Retrying the same request will not help
[511]Network Authentication Required
The client must sign in to the network first, as with a hotel or airport Wi-Fi portal.
Send it when Captive portals send it. Apps do not.
Fix the request before retrying
Which code to pick when two seem right
- 400 vs 422
- Send 400 when the server cannot parse the request, such as broken JSON or a missing header. Send 422 when the JSON parses fine but the values fail validation, such as an email without an @. Many APIs use 400 for both, which is fine if clients get a field-by-field error list.
- 401 vs 403
- 401 means the request has no valid credentials, so the caller should sign in again. 403 means the caller is signed in and still not allowed. Re-sending the same token never fixes a 403.
- 404 vs 410
- 404 says there is nothing here, and it may come back. 410 says it existed and was removed for good, which search engines treat as a stronger signal to drop the page.
- 301 vs 302 vs 307 vs 308
- 301 and 308 are permanent, 302 and 307 are temporary. 301 and 302 let clients change a POST into a GET, while 307 and 308 keep the method and body. For a moved API endpoint that takes POST, use 308.
- 502 vs 503 vs 504
- 502 means the proxy got a bad answer from your app. 503 means your app or proxy is deliberately not taking traffic, often during overload. 504 means the proxy waited and your app never answered in time.
- 200 vs 201 vs 204
- 200 returns a result, 201 means a new resource was created, 204 means success with no body. Use 202 when the work was queued and is not done yet.
How to use it
- Type a status code like 429, a class like 5xx, or a word like redirect or timeout into the box. The list narrows as you type.
- To compare two codes, type them with vs between, such as 422 vs 400. They appear side by side with what to send and which one to pick.
- Use the 1xx to 5xx buttons to see one class at a time.
- Read the "Send it when" line for the rule of thumb on when your app should return that code, and the retry line for what a client should do next.
- Press Copy on any code to paste its meaning into a pull request, API doc or error message.
Questions
- What is the difference between 400 and 422?
- 400 Bad Request means the server could not parse the request at all, for example malformed JSON. 422 Unprocessable Content means the request parsed, but the values break your rules, for example a required field is empty. Frameworks that validate bodies, such as Rails and FastAPI, default to 422.
- What is the difference between 401 and 403?
- 401 means the caller is not authenticated: the token is missing, expired or wrong. 403 means the caller is authenticated but does not have permission. Return 401 to prompt a sign in and 403 when signing in again would not change the answer.
- Which status code should an API return for validation errors?
- 422 is the most precise choice for well formed requests with invalid values, and 400 is the common alternative. Pick one, use it everywhere, and return a JSON body that lists each failing field.
- What is the difference between 502, 503 and 504?
- All three are server side failures reported by a gateway or proxy. 502 is an invalid response from your app, 503 is the service refusing traffic for now, and 504 is your app taking too long to respond. 502 usually points to a crashed process, 504 to a slow request.
- Should I return 404 or 403 for something the user may not see?
- Return 404 when you do not want to reveal that the record exists, such as another customer's invoice. Return 403 when it is fine for the caller to know it exists and they lack access.
- Which status codes should I alert on?
- 5xx responses are the ones that mean your code or infrastructure failed, so those belong in your error tracking. Most 4xx are caused by the client, but a sudden jump in 401, 404 or 429 often points to a bad deploy, a broken link or an abusive client.