|
400
|
Bad Request
RFC 9110
|
The server cannot process the request because the syntax, parameters, headers, or body are invalid. |
Common with invalid JSON, missing required values, malformed URLs, or abnormal headers. |
Check the request body format, Content-Type, query parameters, and server validation logs.
Related: 422
|
|
401
|
Unauthorized
RFC 9110
|
Authentication is required or the provided credentials are invalid. |
Used when a login token is missing, an API key expired, or the Authorization header is incorrect. |
Check the WWW-Authenticate header, token expiry, authentication scheme, and whether cookies are sent.
Related: 403, 407
|
|
402
|
Payment Required
RFC 9110
|
Reserved for payment-required scenarios, but its standard meaning is not widely established. |
Some APIs and payment services use it unofficially for payment, credit, or subscription problems. |
Check the service-specific API documentation for the actual meaning of 402 and the recovery path.
Related: 403, 429
|
|
403
|
Forbidden
RFC 9110
|
The server understood the request but refuses to allow access. |
Common with insufficient permissions, IP blocks, administrative policy, or access to private resources. |
Check authorization policy, ACLs, WAF rules, file permissions, and routing rules separately from authentication.
Related: 401, 404, 451
|
|
404
|
Not Found
RFC 9110
|
The requested resource cannot be found, or the server is not revealing whether it exists. |
Most common with URL typos, deleted pages, incorrect routes, or intentionally hidden resources. |
Check internal links, sitemaps, redirects, routing tables, and replacement URLs for deleted content.
Related: 410, 403, 451
|
|
405
|
Method Not Allowed
RFC 9110
|
The resource exists, but the requested HTTP method is not allowed. |
Occurs when POST is sent to a GET-only URL or when an API route is configured for different methods. |
Check the Allow header, router method definitions, and proxy method restriction policies.
Related: 404, 501
|
|
406
|
Not Acceptable
RFC 9110
|
The server cannot provide a representation matching the client's Accept headers. |
Can occur when the client requests only unsupported media types, languages, or encodings. |
Check the Accept, Accept-Language, and Accept-Encoding headers and the server's content negotiation settings.
Related: 415
|
|
407
|
Proxy Authentication Required
RFC 9110
|
Authentication is required before the client can use the proxy. |
Seen in corporate networks, security proxies, and gateway authentication environments. |
Check Proxy-Authenticate and Proxy-Authorization headers and the network proxy configuration.
Related: 401, 305
|
|
408
|
Request Timeout
RFC 9110
|
The server did not receive the complete client request within the time it was willing to wait. |
Can happen with slow networks, large uploads, keep-alive timeouts, or load balancer timeouts. |
Check client retry behavior, upload size, keep-alive settings, and proxy timeout values.
Related: 504
|
|
409
|
Conflict
RFC 9110
|
The request conflicts with the current state of the resource. |
Often used for duplicate creation, version conflicts, concurrent edits, or invalid state transitions. |
Check resource versions, ETags, duplicate keys, and business state transition rules.
Related: 412, 422
|
|
410
|
Gone
RFC 9110
|
The resource existed in the past but has been permanently removed. |
More specific than 404 when you want to clearly tell search engines and clients that a page was deleted. |
Use 301 if there is a replacement URL; use 410 with sitemap cleanup when permanent removal is correct.
Related: 404, 301
|
|
411
|
Length Required
RFC 9110
|
The server rejects the request because it does not include Content-Length. |
Can occur when a server or gateway must know the request body length in advance. |
Check Content-Length, Transfer-Encoding, and the streaming behavior of the client library.
Related: 413
|
|
412
|
Precondition Failed
RFC 9110
|
A precondition in a conditional request, such as If-Match, failed. |
Used for concurrent edit prevention, cache revalidation, and ETag-based updates. |
Compare If-Match, If-None-Match, and If-Unmodified-Since with the current resource version.
Related: 304, 409, 428
|
|
413
|
Content Too Large
RFC 9110
|
The request body is larger than the server is willing to accept. |
Common with file upload limits, JSON body size limits, and proxy body size restrictions. |
Check upload limits across the server, proxy, CDN, and application.
Related: 411, 431
|
|
414
|
URI Too Long
RFC 9110
|
The request URI is longer than the server can process. |
Can happen with very long query strings, faulty redirect loops, or excessive data placed in a GET URL. |
Move long data into a POST body and check URI length limits in proxies and servers.
Related: 400, 431
|
|
415
|
Unsupported Media Type
RFC 9110
|
The server does not support the media type of the request body. |
Occurs when a JSON API receives the wrong Content-Type or an unsupported file format is uploaded. |
Check Content-Type, file extension, multipart settings, and whether the server parser is registered.
Related: 406, 422
|
|
416
|
Range Not Satisfiable
RFC 9110
|
The requested Range cannot be served because it does not fit the resource size. |
Occurs in resumable downloads or streaming when the requested range is outside the file size. |
Check the Range header, Content-Range, file size, and stale cached metadata.
Related: 206
|
|
417
|
Expectation Failed
RFC 9110
|
The server cannot satisfy the expectation given in the Expect header. |
Can occur when a server or proxy does not support expectations such as Expect: 100-continue. |
Remove the Expect header or confirm that the server supports 100 Continue handling.
Related: 100
|
|
418
|
I'm a teapot
RFC 2324 / RFC 9110
|
A code originating from an April Fools' RFC, mainly with historical and cultural meaning rather than practical error handling. |
Some services use it for playful responses, tests, or developer culture, but it is not recommended for ordinary API design. |
For production APIs, use a clear 4xx or 5xx status code with a well-defined meaning.
Related: 400
|
|
421
|
Misdirected Request
RFC 9110
|
The request was sent to a server that cannot produce a response for it. |
Can happen when HTTP/2 connection reuse, TLS/SNI, CDN, or reverse proxy routing is misconfigured. |
Check Host, SNI, certificates, HTTP/2 connection coalescing, and CDN origin routing.
Related: 400, 502
|
|
422
|
Unprocessable Content
RFC 9110
|
The request syntax is valid, but the content is semantically unprocessable. |
Common for API validation failures, business rule violations, and invalid field values. |
Decide in your API rules whether 400 means format errors and 422 means semantic or validation errors.
Related: 400, 409, 415
|
|
423
|
Locked
RFC 4918
|
The target resource is locked, so the request cannot be processed. |
Used for file edit locks, collaborative documents, and WebDAV resource locks. |
Check the lock owner, lock expiry, unlock API, and conflict handling policy.
Related: 409, 424
|
|
424
|
Failed Dependency
RFC 4918
|
The current request cannot be performed because a previous dependent operation failed. |
Used when multiple operations depend on one another and failure of an earlier operation causes a later one to fail. |
Make the failed prior operation and the dependency relationship clear in the response body.
Related: 207, 423
|
|
425
|
Too Early
RFC 8470
|
The server refuses to process a request that may be too early and risky to replay. |
Can be used with TLS 1.3 0-RTT early data when replay attack risk exists. |
Ensure non-idempotent requests are not sent with 0-RTT, and verify client and server settings.
Related: 429, 503
|
|
426
|
Upgrade Required
RFC 9110
|
The server requires the client to upgrade protocols before it will handle the request. |
Used when a specific upgrade is required, such as an HTTP version, TLS, or WebSocket. |
Check the Upgrade header, supported protocols, and whether proxies forward upgrade requests.
Related: 101
|
|
428
|
Precondition Required
RFC 6585
|
The server requires a conditional request header. |
Used to prevent lost updates from concurrent edits by requiring a condition such as If-Match. |
Provide API documentation and error messages that tell clients to read the ETag and update with If-Match.
Related: 412, 409
|
|
429
|
Too Many Requests
RFC 6585
|
The client sent too many requests within a given time period. |
Common with API rate limits, login attempt limits, bot blocking, and excessive refresh behavior. |
Check Retry-After, rate limit headers, per-user or per-token limits, and backoff strategy.
Related: 403, 503
|
|
431
|
Request Header Fields Too Large
RFC 6585
|
The overall request headers or a specific header field are too large. |
Can occur when cookies become too large or when authentication tokens, tracking headers, or proxy-added headers accumulate. |
Reduce Cookie size, Authorization header size, and headers added by proxy chains.
Related: 400, 413, 414
|
|
451
|
Unavailable For Legal Reasons
RFC 7725
|
The resource cannot be provided for legal reasons. |
Used when access to content is restricted by court orders, government requests, copyright notices, or local regulations. |
Confirm that the code is used to transparently identify a legal requirement, unlike a generic 403 or 404.
Related: 403, 404, 410
|