HTTP Status Codes
HTTP Status Codes
HTTP status codes are three-digit numbers returned by a server after receiving a request.
They tell the client whether the request was successful, redirected, or failed.
Status Code Categories
| Range | Category | Meaning |
|---|---|---|
| 100–199 | 1xx | Informational |
| 200–299 | 2xx | Successful |
| 300–399 | 3xx | Redirection |
| 400–499 | 4xx | Client Error |
| 500–599 | 5xx | Server Error |
1xx — Informational
These codes mean the server has received the request and is continuing to process it.
100 — Continue
The server received the initial part of the request and the client can continue sending the rest.
101 — Switching Protocols
The server agrees to switch to another communication protocol.
Example: HTTP → WebSocket.
102 — Processing
The server has received the request but is still processing it.
103 — Early Hints
The server sends some information before the final response is ready, often to help the browser load resources early.
2xx — Success
These codes mean the request was successfully processed.
200 — OK
The request was successful.
GET /users → 200 OK
201 — Created
A new resource was successfully created.
POST /users → 201 Created
202 — Accepted
The server accepted the request, but processing has not finished yet.
Example: A video-processing job has started in the background.
203 — Non-Authoritative Information
The request succeeded, but the returned information may have been modified by an intermediary.
204 — No Content
The request succeeded, but there is no response body.
Common example: Successful DELETE.
205 — Reset Content
The request succeeded and the client should reset the current view or form.
206 — Partial Content
The server is returning only part of a resource.
Example: Downloading a large video in pieces.
207 — Multi-Status
Provides multiple status results for different operations or resources.
Commonly associated with WebDAV.
208 — Already Reported
The same resource has already been reported in a previous part of the response.
226 — IM Used
The server successfully completed a request using instance-manipulation techniques.
Most REST API developers rarely use this.
3xx — Redirection
These codes tell the client that it may need to take another action, usually involving another URL or cached resource.
300 — Multiple Choices
There are multiple possible representations or locations for the requested resource.
301 — Moved Permanently
The resource has permanently moved to another URL.
302 — Found
The resource is temporarily available at another URL.
303 — See Other
The client should retrieve the resource using another URL, usually with GET.
304 — Not Modified
The resource has not changed since the client's cached version.
The client can use its cached copy.
305 — Use Proxy
The client was instructed to access the resource through a proxy.
Obsolete and should not normally be used.
306 — Unused
This status code was previously defined but is now reserved and unused.
307 — Temporary Redirect
Temporarily redirect the request while preserving the original HTTP method.
308 — Permanent Redirect
Permanently redirect the request while preserving the original HTTP method.
4xx — Client Errors
These indicate that there is a problem with the request from the client.
400 — Bad Request
The server cannot process the request because it is invalid.
400 Bad Request
Example: Invalid request syntax.
401 — Unauthorized
The request lacks valid authentication credentials.
401 Unauthorized
Think:
"Who are you?"
402 — Payment Required
Reserved for future use, but sometimes used by APIs for payment-related requirements.
403 — Forbidden
The server understands the request but refuses to allow it.
Think:
"I know who you are, but you can't do this."
404 — Not Found
The requested resource does not exist.
GET /users/9999
→ 404 Not Found
405 — Method Not Allowed
The endpoint exists, but the HTTP method is not allowed.
DELETE /users
→ 405 Method Not Allowed
406 — Not Acceptable
The server cannot provide a response in a format acceptable to the client.
407 — Proxy Authentication Required
Authentication with a proxy is required.
408 — Request Timeout
The server waited too long for the client to complete the request.
409 — Conflict
The request conflicts with the current state of the resource.
Example: Creating a user with an email that already exists.
410 — Gone
The resource previously existed but has been permanently removed.
411 — Length Required
The server requires the request to include a Content-Length header.
412 — Precondition Failed
A condition specified in the request was not satisfied.
413 — Content Too Large
The request body is larger than the server allows.
Example: Uploading a 500 MB file when the API allows only 100 MB.
414 — URI Too Long
The requested URL is too long for the server to process.
415 — Unsupported Media Type
The server does not support the format of the request.
Example:
Server accepts JSON
Client sends XML
→ 415
416 — Range Not Satisfiable
The requested portion of a resource cannot be provided.
Example: Requesting bytes 1000–2000 from a file that is only 500 bytes long.
417 — Expectation Failed
The server cannot satisfy the expectation specified in the request.
418 — I'm a Teapot
A humorous status code originally defined as part of an April Fools' specification.
It is not a normal REST API error code.
421 — Misdirected Request
The request was sent to a server that cannot produce a response for that particular request.
422 — Unprocessable Content
The server understands the request, but the submitted data fails validation or cannot be processed.
Very common in FastAPI.
423 — Locked
The requested resource is locked.
Commonly associated with WebDAV.
424 — Failed Dependency
The request failed because another required operation failed.
425 — Too Early
The server is unwilling to process the request because it may be replayed.
426 — Upgrade Required
The client must switch to another protocol.
428 — Precondition Required
The server requires the request to contain certain preconditions.
429 — Too Many Requests
The client has sent too many requests in a given period.
Example:
100 requests/minute allowed
Client sends 150
→ 429 Too Many Requests
This is commonly used for rate limiting.
431 — Request Header Fields Too Large
The request headers are too large.
451 — Unavailable For Legal Reasons
The resource cannot be provided because of legal restrictions.
5xx — Server Errors
These mean something went wrong on the server side.
500 — Internal Server Error
A general unexpected server error occurred.
Example: An unhandled exception in a FastAPI application.
501 — Not Implemented
The server does not support the functionality required to process the request.
502 — Bad Gateway
A server acting as a gateway or proxy received an invalid response from another server.
Client
↓
API Gateway
↓
Backend Server
❌
503 — Service Unavailable
The server is currently unable to handle the request.
Examples:
- Server maintenance
- Server overloaded
- Service temporarily unavailable
504 — Gateway Timeout
A gateway or proxy did not receive a response from an upstream server in time.
505 — HTTP Version Not Supported
The server does not support the HTTP version used in the request.
506 — Variant Also Negotiates
There is an internal configuration problem with content negotiation.
507 — Insufficient Storage
The server does not have enough storage to complete the request.
508 — Loop Detected
The server detected an infinite loop while processing the request.
510 — Not Extended
The server requires additional extensions to fulfill the request.
511 — Network Authentication Required
The client needs to authenticate with the network before accessing the resource.
Example: A Wi-Fi captive portal.
Comments