// Reference Codex
Every HTTP status code, OAuth error, and API-specific term decoded. Standardized protocol errors separated from provider-specific terminology so you stop guessing from the status code alone.
API errors do not all use one universal vocabulary. HTTP status codes have standardized meanings, while individual API providers may define their own error codes, messages, and response fields.
This glossary distinguishes standardized HTTP and protocol errors from common API-specific terminology.
HTTP Status Codes
The server has received the initial portion of the request and is asking the client to continue sending the request.
Common context
The server agrees to switch protocols as requested by the client.
Common context
The server has received and is processing the request, but no final response is available yet.
Common context
The server provides preliminary response headers before the final response.
Common context
HTTP Status Codes
2xx responses indicate that a request was successfully received, understood, and processed. They are not errors, but they are useful when troubleshooting APIs.
The request succeeded.
Common API uses
The request succeeded and resulted in the creation of a new resource.
Common API use
The request has been accepted for processing, but processing has not necessarily completed.
Common API use
The request succeeded, but the returned representation or metadata may have been modified from the origin server's response.
The request succeeded, but there is no content to return in the response.
Common API use
The request succeeded and the client should reset the document or view that initiated the request.
The server is returning only part of the requested resource.
Common API use
HTTP Status Codes
3xx responses generally indicate that the client must take additional action to complete the request or that the requested resource is available elsewhere.
| Code | Name | General Meaning |
|---|---|---|
| 300 | Multiple Choices | Multiple possible representations or destinations |
| 301 | Moved Permanently | Resource permanently moved |
| 302 | Found | Resource temporarily available elsewhere |
| 303 | See Other | Retrieve the result from another URL |
| 304 | Not Modified | Cached version is still valid |
| 305 | Use Proxy | Deprecated proxy instruction |
| 306 | Unused | Reserved/unused status code |
| 307 | Temporary Redirect | Temporary redirect that preserves method |
| 308 | Permanent Redirect | Permanent redirect that preserves method |
The request has multiple possible responses, and the user agent may select one.
The requested resource has been permanently moved to a different URL.
Common API/web causes
What to check
The requested resource is temporarily available at a different URL.
Common context
The server directs the client to another URL to retrieve a representation of the requested resource. The follow-up request is normally performed using GET.
Common context
The requested resource has not changed since the version stored by the client or cache.
Common context
The request was intended to be accessed through a proxy.
This status code is no longer used.
The requested resource is temporarily available at another URL. Unlike some historical uses of 302, 307 explicitly requires the client to preserve the original HTTP method and request content when following the redirect.
A request such as:
POST /api/upload
may be temporarily redirected while remaining a POST.The requested resource has permanently moved to another URL. Like 307, the client should preserve the original HTTP method and request content when following the redirect.
POST /api/v1/users
may permanently redirect to:
POST /api/v2/usersIf an API request unexpectedly returns a 3xx response, check:
Key distinctions between redirection status codes.
301 — Moved Permanently
302 — Found
Both indicate temporary redirection.
Both indicate permanent redirection.
304 Not Modified is different from most other 3xx responses. It does not tell the client to visit another URL. Instead, it tells the client that its existing cached representation remains valid.
Phantom Audit Tip
When debugging an API, don't automatically treat every non-2xx response as a failure. A 304 can indicate successful cache validation, while a 301, 302, 307, or 308 may indicate that an endpoint has moved or that an intermediary is redirecting the request.
HTTP Status Codes
4xx responses generally indicate that something about the request is invalid, unacceptable, unauthorized, or otherwise cannot be fulfilled by the server.
The server cannot or will not process the request because it considers the request invalid.
Common API causes
The request lacks valid authentication credentials.
Common causes
The status code is reserved for future use. Some APIs use 402 for billing, payment, subscription, or quota-related conditions.
The server understood the request but refuses to fulfill it.
Common causes
Common distinction
The server cannot find the requested resource.
Common API causes
The HTTP method is recognized by the server but is not supported for the requested resource.
DELETE /users/123
when the endpoint only supports GET.A server should provide an Allow header indicating the methods supported by the target resource.
The server cannot provide a response representation that satisfies the client's content-negotiation requirements.
Common API context
Authentication with an intermediary proxy is required before the request can proceed.
The server did not receive a complete request within the time it was prepared to wait.
The request conflicts with the current state of the target resource.
Common API causes
The requested resource is no longer available and is expected to remain unavailable.
Difference from 404
The server refuses to process the request because it requires a valid Content-Length header.
A condition supplied with the request was not satisfied.
Common API context
The request content is larger than the server is willing or able to process.
Common causes
The requested URI is longer than the server is willing to interpret.
Common API cause
The server refuses the request because the media format of the request content is not supported.
The API expects:
Content-Type: application/json
but receives:
Content-Type: text/xmlThe requested range of a resource cannot be fulfilled.
Common API context
The server cannot meet the requirements specified in the request's Expect header.
This status code is currently registered as unused.
The request was directed at a server that cannot produce a response for the requested target.
Common context
The server understands the content type and syntax of the request but cannot process the contained instructions.
Common API causes
{
"age": -5
}
The JSON is syntactically valid, but the API may reject the value because it violates the application's rules.The target resource is locked and cannot currently be modified.
Common context
The requested action could not be performed because it depended on another action that failed.
Common context
The server is unwilling to process the request because doing so could create a replay risk.
Common context
The server refuses the request using the current protocol and indicates that the client may succeed after upgrading to another protocol. The response should include an Upgrade header identifying the required protocol.
The server requires the request to be conditional.
Common purpose
Common API context
The client has sent too many requests within a given period.
Common causes
A response may include a Retry-After header indicating when the client should try again.
The server refuses the request because its request headers are too large.
Common causes
The server is denying access because of a legal demand.
Common context
The use of 451 does not necessarily establish whether the requested resource actually exists.
HTTP Status Codes
5xx responses generally indicate that the server encountered a problem while attempting to fulfill an apparently valid request.
The server encountered an unexpected condition that prevented it from fulfilling the request.
Common causes
The server does not support the functionality required to fulfill the request.
Important distinction
A server acting as a gateway or proxy received an invalid response from an upstream server.
Example architecture:
Client -> API Gateway -> Backend Service
If the gateway receives an invalid response from the backend, a 502 may result.The server is currently unable to handle the request.
Common causes
A Retry-After header may indicate when the client should retry.
A gateway or proxy did not receive a timely response from an upstream server.
Common distinction
The server does not support the HTTP version used in the request.
The server has an internal configuration error in which the selected variant resource is itself configured to participate in content negotiation in a way that cannot be completed.
Common context
The server requires further extensions to the request before it can fulfill it.
Common context
The client must authenticate with the network before it can access the requested resource.
Common context
Some HTTP status codes are associated with WebDAV or other HTTP extensions rather than ordinary REST APIs. They remain useful to know because developers may encounter them in APIs, file systems, enterprise systems, and WebDAV services.
Provides separate status information for multiple resources or operations.
Indicates that a resource's members have already been reported in an earlier part of a WebDAV response.
The requested resource is locked.
The requested action failed because a dependent action failed.
The server cannot store the representation needed to complete the request.
The server detected an infinite loop while processing the request.
OAuth defines several error values that can appear in authorization and token responses.
The request is missing a required parameter, contains an invalid parameter value, repeats a parameter, or is otherwise malformed.
Common HTTP response
Client authentication failed.
Possible causes
The supplied authorization grant is invalid, expired, revoked, malformed, or otherwise unsuitable for the requested operation.
Common context
The client is not authorized to use the requested authorization grant type or method.
The authorization server does not support the requested grant type.
The requested scope is invalid, unknown, malformed, or otherwise unacceptable.
The resource owner or authorization server denied the authorization request.
The authorization server does not support the requested response type.
The authorization server encountered an unexpected condition that prevented it from fulfilling the request.
The authorization server is temporarily unable to handle the request.
Common causes
OAuth bearer-token usage defines additional error values for protected-resource requests.
The request is malformed or does not correctly contain the required access-token information.
Common HTTP response
The supplied access token is expired, revoked, malformed, or otherwise invalid.
Common HTTP response
The access token does not provide sufficient privileges to perform the requested operation.
Common HTTP response
Modern HTTP APIs may use the standardized Problem Details format defined by RFC 9457. A Problem Details response commonly uses Content-Type: application/problem+json.
{
"type": "https://example.com/problems/invalid-request",
"title": "Invalid Request",
"status": 400,
"detail": "The supplied account ID is invalid.",
"instance": "/requests/12345"
}Identifies the type of problem using a URI reference. The type can point to documentation describing the problem. If omitted, the default value is about:blank.
A short, human-readable summary of the problem type. The title generally describes the type of problem rather than the individual occurrence.
Contains the HTTP status code associated with the problem.
400Provides a human-readable explanation specific to the particular occurrence of the problem. It should generally help the client understand or correct the problem.
Identifies the specific occurrence of the problem. This can be useful for troubleshooting, support, logging, or forensic purposes.
The following terms are commonly encountered in APIs but are not universal HTTP status codes. Their exact meaning can vary between API providers.
The supplied API key is invalid, expired, revoked, malformed, or otherwise unacceptable.
The API expected an API key but did not receive one.
The supplied authentication credentials could not be accepted.
The endpoint requires authentication before it can be used.
Access to the requested operation or resource was denied.
The authenticated client does not have the required permission.
The API refuses to permit the requested operation.
The requested resource could not be found.
The requested resource could not be located.
A required parameter was not provided.
A supplied parameter is invalid.
An argument supplied to the API is invalid.
The request does not satisfy the API's requirements.
The request does not have the expected structure or format.
The request body contains malformed JSON or JSON that the API cannot accept.
One or more submitted values failed application-level validation.
Common examples
The submitted value or resource conflicts with an existing one because it is considered a duplicate.
The requested resource already exists.
The requested operation conflicts with the current state of a resource.
The requested HTTP method is not supported for the endpoint.
The supplied content format is not supported by the API.
The request exceeds a size limit imposed by the API.
The request payload exceeds an allowed size.
The client has exceeded a configured request-rate limit.
Common HTTP status
The client has exhausted an allocated usage quota.
Examples
A configured usage or resource limit has been exceeded.
The service is temporarily unable to process the request.
Common HTTP status
The server encountered an unexpected internal problem.
Common HTTP status
An operation exceeded the amount of time allowed for completion.
The server or API gateway did not receive or complete the request within an expected time period.
A gateway or intermediary did not receive a timely response from an upstream service.
Common HTTP status
A dependent or upstream service returned an error.
A required internal or external service failed.
An operation involving a database failed.
The service has an invalid, incomplete, or incompatible configuration.
The requested functionality is not implemented.
Common HTTP status
API providers frequently include additional fields beyond the standardized Problem Details members. The following are common conventions, but they are not all standardized HTTP fields.
An application-specific identifier for the error.
{
"code": "INVALID_ACCOUNT"
}A human-readable description of the error.
A general-purpose error identifier or object.
An application-specific error identifier.
A human-readable description of an application-specific error.
A human-readable description of an error.
Common context
A collection of individual validation or processing errors.
An identifier associated with a particular request.
Common purpose
An identifier used to associate related operations or requests across systems.
An identifier used to correlate activity across distributed services and tracing systems.
A timestamp indicating when the error or request occurred.
The endpoint or request path associated with the error.
Identifies the input field associated with a validation error.
Identifies the request parameter associated with an error.
Provides information about when a client should attempt the request again.
These are especially common when an API accepts forms, JSON, or structured data.
A required value was not provided.
The value does not match the required format.
The value has an unexpected data type.
The API expects a number but receives a string.The supplied value is outside the permitted range.
The supplied value is shorter than the minimum allowed length.
The supplied value exceeds the maximum allowed length.
The supplied value is not one of the values accepted by the API.
The supplied value is syntactically valid but is not supported by the API.
A required field is absent.
A particular field contains an invalid value.
Two or more fields contain values that cannot be used together.
These terms frequently appear in authentication-related responses but are not universal HTTP status codes.
The authentication or access token has expired.
The token has been revoked and can no longer be used.
The supplied token is invalid.
The user's authenticated session has expired.
The server cannot accept the supplied session information.
The account has been temporarily or permanently locked.
The account has been disabled.
Multi-factor authentication is required before the requested operation can proceed.
The supplied multi-factor authentication information could not be verified.
The API requires an additional verification step.
These terms are provider-specific unless the API documentation says otherwise.
The API requires payment or an active subscription before the requested operation can proceed.
Possible HTTP status
The requested feature requires an active subscription.
The user's current subscription plan does not permit the requested amount of usage.
The allocated usage quota has been exhausted.
The account has used all available credits.
A billing-related operation failed.
A payment attempt was unsuccessful.
The requested file could not be located.
The uploaded or requested file exceeds an allowed size.
The file type is not supported.
The supplied file is malformed, corrupted, or otherwise unacceptable.
The file upload could not be completed.
The requested file could not be downloaded successfully.
The account or service has exceeded its available storage allocation.
A required upstream service is currently unavailable.
A required dependency cannot currently be reached or used.
The service could not establish a required connection.
A connection attempt exceeded the permitted time.
The service did not receive data from a connected service within the expected time.
The service could not complete a write operation within the expected time.
A DNS-related problem prevented the service from resolving a required hostname.
A network-related failure prevented the operation from completing.
Check
Check
Check
Check
Check
Check
Check
Check
Check
Check
The problem is likely on the server side, although the request may have triggered an unhandled server-side condition.
Check
Check
Check
Check
400 Bad Request
422 Unprocessable Content
401 Unauthorized
403 Forbidden
404 Not Found
410 Gone
405 Method Not Allowed
501 Not Implemented
408 Request Timeout
504 Gateway Timeout
409 Conflict
422 Unprocessable Content
429 Too Many Requests
503 Service Unavailable
502 Bad Gateway
504 Gateway Timeout
When troubleshooting an API error, examine more than the HTTP status code.
Phantom Audit Tip
Never assume that an HTTP status code alone explains the entire problem.
An API error does not automatically mean that the API itself is broken. Errors can originate from many sources.
Phantom Audit Tip
The HTTP status code tells you the general class of problem. The API's response body, documentation, logs, and surrounding context often provide the information needed to determine the actual cause. When in doubt: read the response body, check the API documentation, and investigate the specific error code rather than guessing from the HTTP status alone.