# apiguide.dev, full text > A language-agnostic reference for HTTP API design: problem types, status codes, headers, methods, guides, specifications and tools. 437 pages follow, each starting with a level-one heading and its source URL. The index is https://apiguide.dev/llms.txt, and every page is also available alone by appending .md to its URL. Content is CC BY-SA 4.0. --- # Account Frozen > Use 403 with an Account Frozen error when credentials are valid but the account itself has been suspended, locked, or placed under review, so no action can proceed regardless of the caller's permissions. Source: https://apiguide.dev/errors/account-frozen Problem type URI: https://apiguide.dev/errors/account-frozen Status: 403 Forbidden Updated: 2026-10-14 ## When to use it Use 403 with an Account Frozen error when credentials are valid but the account itself has been suspended, locked, or placed under review, so no action can proceed regardless of the caller's permissions. Typical triggers are unpaid invoices past a grace period, a fraud or compliance hold, a security lockout after suspicious activity, or an account pending closure. Unlike a permissions failure, the block applies to the whole account rather than a single endpoint, so retrying against another route will fail the same way. Say what lifted state the client needs to reach and who can lift it. ## When not to use it Do not use this when the account is active and simply out of money. That is `insufficient-funds` and the client can resolve it themselves. Do not use this when the token is missing, malformed, or expired (use `unauthorized` or `expired-authentication-token`), or when an active account lacks the scope for one specific operation (use `insufficient-scope`). ## Example response ```json { "type": "https://apiguide.dev/errors/account-frozen", "title": "Account Frozen", "status": 403, "detail": "This account is frozen pending a billing review and cannot make API requests.", "instance": "/v1/orders", "reason": "billing_review", "frozenAt": "2026-08-27T09:14:00Z", "contact": "https://support.example.com/appeals" } ``` Keep the `reason` a stable machine-readable value so clients can branch on it, and put the human explanation in `detail`. Do not disclose fraud or compliance specifics that would help an attacker probe your review process. Point them at a support channel instead. --- # Bad Gateway > Use 502 Bad Gateway when your server, acting as a gateway or proxy, got a response from the server behind it and that response was unusable. Source: https://apiguide.dev/errors/bad-gateway Problem type URI: https://apiguide.dev/errors/bad-gateway Status: 502 Bad Gateway Updated: 2026-10-14 ## When to use it Use 502 Bad Gateway when your server, acting as a gateway or proxy, got a response from the server behind it and that response was unusable. RFC 9110 defines it as a server that "received an invalid response from an inbound server it accessed while attempting to fulfill the request". The upstream did answer, and the answer was broken: a response that is not valid HTTP, a connection closed partway through the response, a body that is truncated or cannot be parsed, or a payload that does not match the contract the gateway depends on. The same applies to an API that calls a third-party service on the client's behalf, such as a payment processor or a shipping carrier, and relays the result. If that upstream returns something your service cannot use, 502 tells the client the fault is upstream of you and not in its request. A transparent proxy is different: when the upstream returns a well-formed 500, the proxy forwards that response unchanged, because it was a valid response. 502 is a server error, so the client did nothing wrong and the same request may succeed later. Upstream failures are often brief, so retrying a safe or idempotent request with backoff is reasonable. Do not retry a non-idempotent request automatically unless it carries an [`Idempotency-Key`](/headers/idempotency-key), because the upstream may have acted on it before its response broke. ## When not to use it Do not use it when the upstream never answered in time. That is `gateway-timeout` (504). The split is simple: 502 means the upstream answered badly; 504 means it did not answer before you gave up. Do not use it when your own service is overloaded, in maintenance or deliberately shedding load. That is `service-unavailable` (503), which can carry [`Retry-After`](/headers/retry-after). If you know the upstream is down for a while (an open circuit breaker, a provider's announced maintenance), 503 with `Retry-After` gives the client more to work with than a series of 502s. Do not use it for a bug in your own code, including your code mishandling a perfectly valid upstream response. That is `internal-server-error` (500). Blaming the upstream for your own parsing bug sends whoever is on call to the wrong system. Do not pass an upstream's 4xx through as a 502. If the upstream rejected the request because of something the client sent, map it to the matching 4xx so the client can fix it. ## Example response ```json { "type": "https://apiguide.dev/errors/bad-gateway", "title": "Bad Gateway", "status": 502, "detail": "The payment provider returned an invalid response. The charge was not confirmed; retry with the same Idempotency-Key.", "instance": "/v1/charges", "upstream": "payments" } ``` If you name the upstream, use a stable logical name such as `payments`, never an internal hostname, IP address or port. A 502 body is often generated by a proxy rather than your application, so configure the proxy's error page to emit `application/problem+json` too, or clients will get an HTML page from an API endpoint. --- # Date Not Acceptable > Use 400 with Date Not Acceptable when you reject a request because the value of its `Date` header falls outside the window of time you accept requests in. Source: https://apiguide.dev/errors/date-not-acceptable Problem type URI: https://iana.org/assignments/http-problem-types#date Alias: https://apiguide.dev/errors/date-not-acceptable (registered with IANA; send the registered URI) Status: 400 Bad Request Updated: 2026-10-17 ## When to use it Use 400 with Date Not Acceptable when you reject a request because the value of its [`Date`](/headers/date) header falls outside the window of time you accept requests in. The usual reason to have such a window is replay protection: if you only accept requests dated within the last few minutes, you only have to remember the requests you have seen within those few minutes. The type is defined in Section 6.5.2 of RFC 9458, Oblivious HTTP, for an Oblivious Gateway Resource that uses `Date` for anti-replay. It is registered in the IANA HTTP Problem Types registry as `https://iana.org/assignments/http-problem-types#date`, so send that URI as the `type`. The registry entry is not restricted to Oblivious HTTP, and the meaning, "the date in your request is not acceptable", fits any server that rejects requests on a replay window. Send your own `Date` in the response. RFC 9458 has the client correct for clock skew by retrying once with your `Date` value, adjusted by [`Age`](/headers/age) if the response came from a cache, and it forbids retrying with an adjusted date more than once. Because the response depends on the request's `Date`, either send [`Cache-Control: no-store`](/headers/cache-control) or include `date` in [`Vary`](/headers/vary), as the RFC recommends. ## When not to use it Do not use it when `Date` is missing or does not parse. That is a malformed request, and a plain 400 or `malformed-request-body` says so; this type claims the value was read and judged out of range. Do not use it for an expired token or a stale signature `created` parameter. Those are different clocks with different fixes: an expired token is `expired-authentication-token`, and the client renews it rather than adjusting its clock. Do not keep the window secret, and do not use this type to hide it. RFC 9458 notes that a client can find the window by probing, so a vague error buys nothing. ## Example response ```http HTTP/1.1 400 Bad Request Date: Fri, 17 Oct 2026 09:30:00 GMT Content-Type: application/problem+json Cache-Control: no-store ``` ```json { "type": "https://iana.org/assignments/http-problem-types#date", "title": "Date Not Acceptable", "status": 400, "detail": "The request was dated 09:14:02 GMT, outside the 5 minute window this server accepts.", "instance": "/v1/transfers" } ``` --- # Invalid Digest Values > Use 400 with an Invalid Digest Values error when a `Content-Digest` or `Repr-Digest` field parses, names an algorithm you support, but carries a value that algorithm could never produce. Source: https://apiguide.dev/errors/digest-invalid-values Problem type URI: https://iana.org/assignments/http-problem-types#digest-invalid-values Alias: https://apiguide.dev/errors/digest-invalid-values (registered with IANA; send the registered URI) Status: 400 Bad Request Updated: 2026-10-17 ## When to use it Use 400 with an Invalid Digest Values error when a [`Content-Digest`](/headers/content-digest) or [`Repr-Digest`](/headers/repr-digest) field parses, names an algorithm you support, but carries a value that algorithm could never produce. The commonest case is the wrong length: a SHA-256 digest is 32 bytes and a SHA-512 digest is 64, so anything else is wrong before you hash a single byte of content. A value that is not a Byte Sequence at all, or whose base64 does not decode, belongs here too. Skip computing the digest when you know the value is invalid. There is nothing to compare it with, and refusing early costs less than hashing a large body for a result you already know. This is the `digest-invalid-values` problem type from the IETF HTTPAPI working group's `draft-ietf-httpapi-digest-fields-problem-types` (Section 3.2 of revision 06), which recommends 400. IANA registered it in the HTTP Problem Types registry on 2026-06-26, so send the registered URI, `https://iana.org/assignments/http-problem-types#digest-invalid-values`, as the `type`. This page's URI resolves too and documents the same problem, but a client that recognizes registered types will only recognize the IANA one. The extension members below use the draft's names. ## When not to use it Do not use this when the value is a well-formed digest that simply does not match the content. That is `digest-mismatched-values`. Do not use this for an algorithm you do not support: you cannot know what a valid value looks like for an algorithm you do not implement. That is `digest-unsupported-algorithms`. Do not use this when the field is not a valid Structured Field Dictionary in the first place, such as a missing `=` or an unterminated Byte Sequence delimiter. The draft scopes its problem types to fields that parse; answer one that does not with a plain 400. ## Example response ```json { "type": "https://iana.org/assignments/http-problem-types#digest-invalid-values", "title": "Invalid Digest Values", "status": 400, "detail": "A digest in the request cannot have come from its hashing algorithm.", "instance": "/v1/items/123", "invalid_digests": [ { "algorithm": "sha-512", "header": "Repr-Digest", "reason": "digest value is not 64 bytes long" } ] } ``` The `reason` is for a developer reading the response, so say exactly what was wrong. An invalid value is a bug in how the client calculates or encodes the digest, so retrying the same request will fail the same way. --- # Mismatched Digest Values > Use 400 with a Mismatched Digest Values error when a request carries a `Content-Digest` or `Repr-Digest` field, the digest uses an algorithm you support, and the value you compute over the content does not match the one the client sent. Source: https://apiguide.dev/errors/digest-mismatched-values Problem type URI: https://iana.org/assignments/http-problem-types#digest-mismatched-values Alias: https://apiguide.dev/errors/digest-mismatched-values (registered with IANA; send the registered URI) Status: 400 Bad Request Updated: 2026-10-17 ## When to use it Use 400 with a Mismatched Digest Values error when a request carries a [`Content-Digest`](/headers/content-digest) or [`Repr-Digest`](/headers/repr-digest) field, the digest uses an algorithm you support, and the value you compute over the content does not match the one the client sent. Something changed the bytes between the client hashing them and you receiving them: a proxy that re-encoded the body, a truncated upload, a client bug that hashed one thing and sent another. Reject the whole request, even if the same field carries a second digest that does match. A client that sends `sha-256` and `sha-512` side by side and gets one wrong has a problem worth surfacing, and accepting the request on the strength of whichever digest happens to match weakens the check for everyone. This is the `digest-mismatched-values` problem type from the IETF HTTPAPI working group's `draft-ietf-httpapi-digest-fields-problem-types` (Section 3.3 of revision 06), which recommends 400. IANA registered it in the HTTP Problem Types registry on 2026-06-26, so send the registered URI, `https://iana.org/assignments/http-problem-types#digest-mismatched-values`, as the `type`. This page's URI resolves too and documents the same problem, but a client that recognizes registered types will only recognize the IANA one. The extension members below use the draft's names. ## When not to use it Do not use this when the digest value could never have come from its algorithm, such as a `sha-512` value that is 32 bytes long. That is `digest-invalid-values`: the sender encoded it wrong, and comparing it to anything is pointless. Do not use this when the request names only algorithms you do not support. That is `digest-unsupported-algorithms`, and the fix is a different algorithm rather than a retry. Do not use this when the field itself does not parse as a Structured Field Dictionary. The draft says its problem types apply only once the field has parsed; a field that does not is a plain 400. ## Example response ```json { "type": "https://iana.org/assignments/http-problem-types#digest-mismatched-values", "title": "Mismatched Digest Values", "status": 400, "detail": "A digest in the request does not match its content. It may have been changed in transit.", "instance": "/v1/items/123", "mismatched_digests": [ { "algorithm": "sha-256", "provided_digest": ":RK/0qy18MlBSVnWgjwz6lZEWjP/lF5HF9bvEF8FabDg=:", "header": "Content-Digest" } ] } ``` Each entry names the algorithm, the field it came from, and the digest the client sent, serialized as a Structured Field Byte Sequence. Never include the digest you computed: the draft leaves it out deliberately, because handing it back turns the endpoint into an oracle for whatever content an attacker wants hashed. A mismatch is often transient, so a client can reasonably retry the identical request once. If it fails again, the bytes are being changed on the way and retrying will not help. --- # Unsupported Hashing Algorithms > Use 400 with an Unsupported Hashing Algorithms error when the only digests a request carries, in `Content-Digest` or `Repr-Digest`, use algorithms you do not support. Source: https://apiguide.dev/errors/digest-unsupported-algorithms Problem type URI: https://iana.org/assignments/http-problem-types#digest-unsupported-algorithms Alias: https://apiguide.dev/errors/digest-unsupported-algorithms (registered with IANA; send the registered URI) Status: 400 Bad Request Updated: 2026-10-17 ## When to use it Use 400 with an Unsupported Hashing Algorithms error when the only digests a request carries, in [`Content-Digest`](/headers/content-digest) or [`Repr-Digest`](/headers/repr-digest), use algorithms you do not support. You cannot check the content, so you cannot accept the integrity claim the client made. The usual cause is a client still using one of the algorithms [Digest Fields](/specifications/digest-fields) registers as Deprecated: `md5`, `sha`, `unixsum`, `unixcksum`, `adler` or `crc32c`. RFC 9530 says those MUST NOT be used where an attacker could be involved, which describes any public API, so supporting only `sha-256` and `sha-512` is the right default and this error is how a client finds that out. Tell the client what would work. Send `Want-Content-Digest` and `Want-Repr-Digest` on the response, listing the algorithms you accept with a weight from 1 to 10, so it can retry with one of them. This is the `digest-unsupported-algorithms` problem type from the IETF HTTPAPI working group's `draft-ietf-httpapi-digest-fields-problem-types` (Section 3.1 of revision 06), which recommends 400. IANA registered it in the HTTP Problem Types registry on 2026-06-26, so send the registered URI, `https://iana.org/assignments/http-problem-types#digest-unsupported-algorithms`, as the `type`. This page's URI resolves too and documents the same problem, but a client that recognizes registered types will only recognize the IANA one. The extension members below use the draft's names. ## When not to use it Do not use this when at least one digest in the field uses an algorithm you support and checks out. RFC 9530 lets a recipient ignore digests it does not understand, which is what lets a client send a new algorithm alongside an established one during a migration. Ignore the unknown members and accept the request. Do not use this just because a `Want-Content-Digest` or `Want-Repr-Digest` on a request names only algorithms you do not support. The draft allows it, but RFC 9530 makes those fields hints and says ignoring them is not a protocol error. Serve the response without the digest rather than failing a request the client could otherwise have used. Do not use this for a supported algorithm with a bad value. That is `digest-invalid-values` or `digest-mismatched-values`. ## Example response ```http HTTP/1.1 400 Bad Request Content-Type: application/problem+json Want-Content-Digest: sha-256=10, sha-512=10 Want-Repr-Digest: sha-256=10, sha-512=10 ``` ```json { "type": "https://iana.org/assignments/http-problem-types#digest-unsupported-algorithms", "title": "Unsupported Hashing Algorithms", "status": 400, "detail": "None of the hashing algorithms in the request is supported. Use sha-256 or sha-512.", "instance": "/v1/items/123", "unsupported_algorithms": [ { "algorithm": "md5", "header": "Content-Digest" } ] } ``` List one entry per unsupported algorithm per field, so a client that sent both `Content-Digest` and `Repr-Digest` can see each one it needs to change. --- # Endpoint Sunset > Use `410 Gone` with an Endpoint Sunset error when a client calls a piece of API surface you have retired on purpose: an endpoint, an operation, or a path-versioned API such as everything under `/v1/`. Source: https://apiguide.dev/errors/endpoint-sunset Problem type URI: https://apiguide.dev/errors/endpoint-sunset Status: 410 Gone Updated: 2026-10-17 ## When to use it Use [`410 Gone`](/status-codes/410) with an Endpoint Sunset error when a client calls a piece of API surface you have retired on purpose: an endpoint, an operation, or a path-versioned API such as everything under `/v1/`. The endpoint was deprecated, its sunset date has passed, and it has been switched off. This is a more specific type than `gone`. `gone` says a resource no longer exists, and it fits a deleted record as well as a retired endpoint. This type says the interface itself was retired as part of a planned migration, which tells the client the problem is in its code, not in its data, and that there is a documented replacement to move to. A client can branch on it to raise an alert for a developer rather than quietly dropping a record ID. It is the end of a lifecycle that starts earlier, with two headers on every successful response. RFC 9745 defines [`Deprecation`](/headers/deprecation), which says when the endpoint was or will be deprecated. RFC 8594 defines [`Sunset`](/headers/sunset), which says when it is expected to stop responding. RFC 9745 says the sunset time MUST NOT be earlier than the deprecation time. RFC 8594 expects that after the sunset time, interactions are likely to produce a client error, a redirect, or no response at all; this type is the client error, made explicit. The [deprecation and sunsetting guide](/guides/deprecation-sunsetting) covers the whole sequence. Put the replacement in the body. A client that hits a retired endpoint in production needs the successor and a migration guide now, not after a search through the changelog. ## When not to use it Do not use it before the sunset date. Until then the endpoint still works: serve it normally, with `Deprecation` and `Sunset` headers. RFC 9745 is explicit that deprecation does not change the behavior of the resource. Do not use it for a single record that was deleted. That is `gone`, or `resource-not-found` (404) if you keep no record of what was deleted. Do not use it for a version selected by a header or media type that you no longer serve. The URI still exists in other versions, so that is `unsupported-api-version`. This type fits when the URI itself is what was retired. Do not use a redirect instead unless the replacement accepts the same request and returns the same response shape. Redirecting a retired endpoint to one with a different contract turns a clear failure into a confusing one. ## Example response ```json { "type": "https://apiguide.dev/errors/endpoint-sunset", "title": "Endpoint Sunset", "status": 410, "detail": "GET /v1/reports was retired on 2026-09-30. Use GET /v2/reports instead.", "instance": "/v1/reports", "deprecatedAt": "2026-03-31T00:00:00Z", "sunsetAt": "2026-09-30T00:00:00Z", "successor": "/v2/reports", "migrationGuide": "https://developer.example.com/migrations/v2-reports" } ``` Before the switch-off, the same endpoint announced both dates on every response, with a `sunset` link relation pointing at the migration guide: ```http HTTP/1.1 200 OK Deprecation: @1774915200 Sunset: Wed, 30 Sep 2026 00:00:00 GMT Link: ; rel="sunset" ``` Keep answering with this type for as long as old clients keep calling. Taking the route away entirely, so it falls through to a generic 404, throws away the one response that tells a stranded client where to go. --- # Expired Authentication Token > Use 401 with an expired authentication token error when the client presents a token (such as a JWT, OAuth token, or API token) that is structurally valid and was previously recognized by the server, but has since passed its expiration timestamp. Source: https://apiguide.dev/errors/expired-authentication-token Problem type URI: https://apiguide.dev/errors/expired-authentication-token Status: 401 Unauthorized Updated: 2026-10-13 ## When to use it Use 401 with an expired authentication token error when the client presents a token (such as a JWT, OAuth token, or API token) that is structurally valid and was previously recognized by the server, but has since passed its expiration timestamp. This allows the client to detect that their session has timed out and programmatically attempt to request a new token using a refresh token, rather than treating the failure as a permanent lack of credentials. ## When not to use it Do not use this if the client sent no token at all, or if the token is completely malformed or unsigned. In those cases, use a generic `unauthorized` error. Also, do not use this if the token is valid but the user lacks the necessary permissions to access the resource; use `insufficient-scope` (403) instead. ## Example response ```json { "type": "https://apiguide.dev/errors/expired-authentication-token", "title": "Expired Authentication Token", "status": 401, "detail": "The access token expired at 2026-07-07T10:00:00Z. Please request a new token.", "instance": "/v1/leads" } ``` Include a `WWW-Authenticate` header describing exactly why the token was rejected, per RFC 6750: ```http WWW-Authenticate: Bearer error="invalid_token", error_description="The access token expired" ``` --- # Failed Dependency > Use `424 Failed Dependency` for an operation that was not performed because it depended on another operation in the same request, and that other operation failed. Source: https://apiguide.dev/errors/failed-dependency Problem type URI: https://apiguide.dev/errors/failed-dependency Status: 424 Failed Dependency Updated: 2026-10-17 ## When to use it Use [`424 Failed Dependency`](/status-codes/424) for an operation that was not performed because it depended on another operation in the same request, and that other operation failed. RFC 4918 defines it as a method that "could not be performed on the resource because the requested action depended on another action and that action failed". Its natural home is inside a batch or compound request. When a [bulk operation](/guides/bulk-operations) contains steps that build on each other, such as creating a customer and then a subscription for that customer, and the first step fails, the second was never attempted. Mark it with this type so the client can tell the step that actually failed from the steps that were skipped because of it. RFC 4918's own example has the same shape: if one command in a [`PROPPATCH`](/methods/proppatch) fails, the rest fail with 424. The same applies to an all-or-nothing batch. If item 3 of 10 fails and the batch rolls back, item 3 carries its own error and the other nine carry this type, so the client knows they were valid and can resubmit them unchanged once item 3 is fixed. Always point at the operation that failed. A 424 that does not say which dependency broke sends the client searching through the whole batch. ## When not to use it Do not use it for the operation that actually failed. That one gets its own, specific problem type, such as `validation-failed` or `resource-conflict`. 424 is only for what failed as a consequence. Do not use it when a downstream service your server calls is down or misbehaving. That is your dependency, not the client's request, and it is a 5xx: `bad-gateway` (502), `gateway-timeout` (504) or `service-unavailable` (503). The name invites this mistake, and it tells the client to fix something it cannot fix. Do not use it for independent items in a batch. If item 4 does not depend on item 3, item 3 failing is no reason to skip item 4: process it and report its own result. Do not return it as the top-level status of a single compound operation. Return the failing step's problem at the top level instead. A top-level 424 tells the client something broke without telling it what. ## Example response Per-item results inside a [`207 Multi-Status`](/status-codes/207) batch response, where operation 1 depended on operation 0: ```json { "results": [ { "status": 422, "error": { "type": "https://apiguide.dev/errors/validation-failed", "title": "Validation Failed", "status": 422, "detail": "The email must be a valid email address.", "operation": 0 } }, { "status": 424, "error": { "type": "https://apiguide.dev/errors/failed-dependency", "title": "Failed Dependency", "status": 424, "detail": "This operation was not attempted because operation 0, which it depends on, failed.", "operation": 1, "dependsOn": 0 } } ] } ``` --- # Feature Disabled > Use `403 Forbidden` with a Feature Disabled error when the caller is authenticated, the request is valid, and the feature it uses is turned off for this account, organization or plan. Source: https://apiguide.dev/errors/feature-disabled Problem type URI: https://apiguide.dev/errors/feature-disabled Status: 403 Forbidden Updated: 2026-10-17 ## When to use it Use [`403 Forbidden`](/status-codes/403) with a Feature Disabled error when the caller is authenticated, the request is valid, and the feature it uses is turned off for this account, organization or plan. Common cases are a capability that is not included in the customer's plan, a beta the account has not been enrolled in, or a feature an admin has switched off in the account's settings. 403 is the right code because the server understood the request and refuses it, and no change of credentials will help. RFC 9110 notes that a request "might be forbidden for reasons unrelated to the credentials", which is this case: the caller's identity and permissions are fine, the account's configuration is not. What the client needs is a different plan, an enrollment, or an admin to flip a setting, so say which. Name the feature with a stable identifier and say how to enable it. A client can then hide the corresponding UI, and a developer reading the log knows whether to talk to sales, support or their own admin. ## When not to use it Do not use it for a feature switched off for everyone, temporarily, with a kill switch or during an incident. Nothing the client does will enable it, and it is expected to come back, so that is a 503: `maintenance-mode` for planned work, `service-unavailable` otherwise. Do not use it when the caller's role lacks permission for an action that is enabled on the account. That is your permission model, which is `forbidden`. When the OAuth token lacks the scope, it is `insufficient-scope`. Feature Disabled is about the account, not the person or the token. Do not use it for an unreleased feature that callers should not know exists. Revealing a feature flag by name in an error leaks your roadmap. RFC 9110 lets a server hide a forbidden resource behind 404, so return `resource-not-found` until the feature is announced. Do not use [`402 Payment Required`](/status-codes/402) for a feature gated by plan. RFC 9110 reserves 402 for future use, and clients have no agreed way to act on it. Do not use [`501 Not Implemented`](/status-codes/501) either. 501 means the server does not support the functionality at all, for anyone, and it is a server error. A feature that exists and is merely off for this account is neither. ## Example response ```json { "type": "https://apiguide.dev/errors/feature-disabled", "title": "Feature Disabled", "status": 403, "detail": "Bulk export is not included in the Starter plan. Upgrade to Business or contact sales to enable it.", "instance": "/v1/exports", "feature": "bulk_export", "enableUrl": "https://example.com/settings/billing" } ``` Keep `feature` a stable machine-readable value, and keep `detail` for the human explanation. Plans and their names change; the identifier a client branches on should not. --- # Forbidden > Use 403 Forbidden when the server knows who the caller is, the credentials are valid, and your authorization rules still refuse this action. Source: https://apiguide.dev/errors/forbidden Problem type URI: https://apiguide.dev/errors/forbidden Status: 403 Forbidden Updated: 2026-10-14 ## When to use it Use 403 Forbidden when the server knows who the caller is, the credentials are valid, and your authorization rules still refuse this action. RFC 9110 defines 403 as a server that "understood the request but refuses to fulfill it", and states that when credentials were provided, the server "considers them insufficient to grant access". This is the general authorization-denied case, decided by your own policy rather than by the token: a member trying to delete a project only an owner can delete, a user editing another user's profile, a role without access to billing data, or a request from outside an IP allowlist. RFC 9110 notes that a request "might be forbidden for reasons unrelated to the credentials", which covers the allowlist case. RFC 9110 also says the client "SHOULD NOT automatically repeat the request with the same credentials". Tell the client what it lacks, such as the role or relationship the action needs, so a human can request access. A bare 403 with no reason leaves them guessing whether to ask an admin, switch accounts or give up. ## When not to use it Do not use it when the caller is not authenticated, or the credentials are missing, malformed or revoked. That is `unauthorized` (401), and an expired token is `expired-authentication-token`. 401 means "authenticate and try again"; 403 means authenticating again will not help. Do not use it when the refusal comes from the OAuth scopes on the access token rather than from your own permission model. That is `insufficient-scope`, also a 403, which carries the RFC 6750 `WWW-Authenticate` challenge so a client can request a token with the right scope. A user who is an owner but holds a `read`-only token gets `insufficient-scope`; a user with a full-scope token who is not an owner gets this type. Do not use it when the whole account is suspended and every request fails regardless of permissions. That is `account-frozen`. Do not use it when the caller should not learn that the resource exists at all. RFC 9110 allows an origin server that wants to hide the existence of a forbidden resource to respond with 404 instead, so use `resource-not-found`. The rule that works: if the caller cannot see the resource at all (another tenant's order ID), return 404; if they can read it but cannot perform this action on it, return 403. Returning 403 for another tenant's IDs confirms which IDs are real. ## Example response ```json { "type": "https://apiguide.dev/errors/forbidden", "title": "Forbidden", "status": 403, "detail": "Only project owners can delete a project. Your role on project prj_8812 is member.", "instance": "/v1/projects/prj_8812", "requiredRole": "owner", "currentRole": "member" } ``` The request that triggers it is valid in every way except who sent it: ```http DELETE /v1/projects/prj_8812 HTTP/1.1 Host: api.example.com Authorization: Bearer eyJhbGciOiJSUzI1NiJ9... ``` RFC 9457 points out that a problem type for a truly generic condition adds little, because a 403 on its own already says "not allowed". This type earns its place through the extension members: a stable, machine-readable reason a client can branch on and show to the user. Do not put internal policy names or rule IDs in it. --- # Gateway Timeout > Use 504 Gateway Timeout when an upstream server (such as Nginx, Apache, an API Gateway, or Cloudflare) acting as a gateway or proxy fails to receive a timely response from the backend application server (like Node.js, Python, or Go) to complete the request. Source: https://apiguide.dev/errors/gateway-timeout Problem type URI: https://apiguide.dev/errors/gateway-timeout Status: 504 Gateway Timeout Updated: 2026-10-14 ## When to use it Use 504 Gateway Timeout when an upstream server (such as Nginx, Apache, an API Gateway, or Cloudflare) acting as a gateway or proxy fails to receive a timely response from the backend application server (like Node.js, Python, or Go) to complete the request. This error tells the client that the request reached the edge network or gateway, but the processing server took too long to respond (e.g. database query lock, infinite loop, or external API timeout). ## When not to use it Do not use 504 if the application server failed with an unhandled error (use 500 Internal Server Error). Do not use this code if the server is down or undergoing maintenance (use 503 Service Unavailable). If the upstream did respond, but with something invalid, empty or unusable, use `bad-gateway` (502). ## Example response ```json { "type": "https://apiguide.dev/errors/gateway-timeout", "title": "Gateway Timeout", "status": 504, "detail": "The upstream gateway server did not receive a timely response from the application server.", "instance": "/v1/leads" } ``` --- # Gone > Use 410 Gone when a resource has been removed on purpose and will not come back. Source: https://apiguide.dev/errors/gone Problem type URI: https://apiguide.dev/errors/gone Status: 410 Gone Updated: 2026-10-17 ## When to use it Use 410 Gone when a resource has been removed on purpose and will not come back. RFC 9110 defines it as access to the target resource being "no longer available at the origin server" with the condition "likely to be permanent", and describes it as telling the recipient that "the resource is intentionally unavailable". In an API this has two common cases: - **A sunset endpoint or version.** An endpoint was deprecated, its [`Sunset`](/headers/sunset) date has passed, and it has been switched off. RFC 8594 says that after the sunset time, interactions are likely to result in client errors, redirects or no response at all. 410 is the client error that says exactly what happened. If you want the `type` itself to say that API surface was retired, rather than a resource deleted, use the narrower `endpoint-sunset`; this type stays correct for both. - **A deleted record you still remember.** The record was hard-deleted and you kept a tombstone, so you can tell a deleted ID apart from one that never existed. 410 is useful because it is final. A client that gets one should stop calling that URI, remove stored references to it and, for a sunset endpoint, migrate. Put the replacement in the body so the client does not have to search the changelog for it. ## When not to use it Do not use it when you do not know whether the resource ever existed or whether its absence is permanent. RFC 9110 is explicit: if the server "does not know, or has no facility to determine" whether the condition is permanent, use 404. That is `resource-not-found`, and it is the right answer for most missing IDs, because most systems do not keep tombstones. Do not use it for a soft delete that can still be undone within a restore window. The resource is not permanently gone, and telling clients to drop their references to something a user may restore tomorrow is wrong. Do not use it before the sunset date. Until then the endpoint still works: serve it normally with `Sunset` and [`Deprecation`](/headers/deprecation) headers. 410 is for after the switch-off. Do not use it for an API version requested in a header or media type that you no longer serve. The resource still exists in other versions, so that is `unsupported-api-version`. 410 fits a path-versioned URI such as `/v1/search` that has been retired, because there the URI itself is what has gone. Do not use it for a method a resource no longer accepts while the resource itself stays. That is `method-not-allowed` (405). ## Example response ```json { "type": "https://apiguide.dev/errors/gone", "title": "Gone", "status": 410, "detail": "GET /v1/search was sunset on 2026-06-30 and has been removed. Use GET /v2/search.", "instance": "/v1/search", "sunsetAt": "2026-06-30T00:00:00Z", "successor": "/v2/search", "migrationGuide": "https://developer.example.com/migrations/v1-search" } ``` Before the switch-off, the same endpoint announced the date on every response: ```http HTTP/1.1 200 OK Deprecation: @1767225600 Sunset: Tue, 30 Jun 2026 00:00:00 GMT Link: ; rel="sunset" ``` RFC 9110 makes 410 heuristically cacheable, so a cache may keep serving it without explicit freshness information. That is usually what you want for a permanent removal. If there is any chance you will bring the URI back, send `Cache-Control` with a short lifetime, or reconsider whether 410 is the right code at all. --- # Idempotency Key Conflict > Use 422 with an Idempotency Key Conflict error when a client sends an `Idempotency-Key` that it has already used, but with a different request payload. Source: https://apiguide.dev/errors/idempotency-key-conflict Problem type URI: https://apiguide.dev/errors/idempotency-key-conflict Status: 422 Unprocessable Content Updated: 2026-10-14 ## When to use it Use 422 with an Idempotency Key Conflict error when a client sends an `Idempotency-Key` that it has already used, but with a different request payload. The server cannot treat the request as a retry of the original, because it is not the same request, and it must not execute it as a new one, because the key says it is a retry. Rejecting it prevents a client bug from silently returning the cached result of a different operation, or duplicating a mutation such as a charge. This follows the IETF HTTPAPI working group's Internet-Draft `draft-ietf-httpapi-idempotency-key-header` (revision -07), which recommends 422 for a key reused with a different payload. The draft is not an RFC and has expired, so treat it as the best available convention rather than a standard. The same draft recommends 409 Conflict for the other misuse of a key: a retry that arrives while the original request with that key is still being processed. Use this same problem type for that case with `status` set to 409, and send a short `Retry-After`. The status code tells the client which case it hit: a 409 can be retried unchanged once the original finishes, while a 422 never succeeds until the client sends the original payload or generates a new key. ## When not to use it Do not use this for an identical retry with a previously seen key. That is the case idempotency keys exist for: return the stored response from the original request, not an error. Do not use this when the key is missing on an operation that requires one. The draft recommends 400 Bad Request for that, with a link to documentation explaining the requirement. It is a malformed request, not a conflict. Do not use this for general business logic conflicts, such as attempting to create a user with an email address that is already registered. In those cases, use `resource-conflict`. ## Example response A key reused with a different payload: ```json { "type": "https://apiguide.dev/errors/idempotency-key-conflict", "title": "Idempotency Key Conflict", "status": 422, "detail": "The Idempotency-Key 'key_abc123' has already been used for a different request payload. Resend the original payload, or use a new key for a new request.", "instance": "/v1/charges" } ``` A retry that arrives while the original request is still in flight uses the same type with 409, and tells the client when to try again: ```http HTTP/1.1 409 Conflict Content-Type: application/problem+json Retry-After: 5 { "type": "https://apiguide.dev/errors/idempotency-key-conflict", "title": "Idempotency Key Conflict", "status": 409, "detail": "A request with Idempotency-Key 'key_abc123' is still being processed. Retry the same request after it completes.", "instance": "/v1/charges" } ``` --- # Idempotency Key Missing > Use `400 Bad Request` with an Idempotency Key Missing error when an operation is documented as requiring an `Idempotency-Key` header and the request arrives without one. Source: https://apiguide.dev/errors/idempotency-key-missing Problem type URI: https://apiguide.dev/errors/idempotency-key-missing Status: 400 Bad Request Updated: 2026-10-17 ## When to use it Use [`400 Bad Request`](/status-codes/400) with an Idempotency Key Missing error when an operation is documented as requiring an [`Idempotency-Key`](/headers/idempotency-key) header and the request arrives without one. Payment, transfer and order-creation endpoints often make the key mandatory, because a retried [`POST`](/methods/post) without one can charge a customer twice. This follows the IETF HTTPAPI working group's Internet-Draft `draft-ietf-httpapi-idempotency-key-header` (revision -07), which says the resource SHOULD reply with 400 and a body that links to documentation explaining the requirement. The draft has expired and is not an RFC, so treat it as the best available convention rather than a standard. Reject the request before doing any work. The whole point of requiring the key is that an unkeyed request cannot be made safe to retry, so processing it anyway defeats the requirement. The [idempotency guide](/guides/idempotency) covers how the key, the stored response and the payload fingerprint fit together. ## When not to use it Do not use it on endpoints where the key is optional. If you accept unkeyed requests, process them without idempotency protection; refusing them only some of the time is worse than either policy. Do not use it when the key is present but has been misused. A key reused with a different payload, or a retry that arrives while the original request is still running, is `idempotency-key-conflict` (422 or 409). Do not use it when the key is present but malformed, such as a value that is not a Structured Fields String as the draft requires, or one longer than your documented limit. That is still a 400, but it is a validation problem with a header the client did send, so say what is wrong with the value rather than that it is missing. Do not reach for [`428 Precondition Required`](/status-codes/428) here. 428 means a conditional header such as [`If-Match`](/headers/if-match) is missing, which is `precondition-required`, and an idempotency key is not a precondition on the resource's state. Do not start requiring the key on an existing endpoint without warning. Every client that sends unkeyed requests today begins failing on its next call, so treat the change as a breaking one and announce it first. ## Example response ```http HTTP/1.1 400 Bad Request Content-Type: application/problem+json Link: ; rel="describedby"; type="text/html" { "type": "https://apiguide.dev/errors/idempotency-key-missing", "title": "Idempotency Key Missing", "status": 400, "detail": "POST /v1/charges requires an Idempotency-Key header. Generate a unique key, such as a UUID, for each new charge and send the same key on every retry of it.", "instance": "/v1/charges", "documentation": "https://developer.example.com/idempotency" } ``` The draft shows both ways of pointing at documentation: a link in the problem body, and a `Link` header with `rel="describedby"`. Sending both costs nothing and serves clients that read only one of them. --- # Insufficient Funds > Use 402 with an Insufficient Funds error when the client is authenticated and authorized to perform the action, but the account backing the request cannot cover its cost. Source: https://apiguide.dev/errors/insufficient-funds Problem type URI: https://apiguide.dev/errors/insufficient-funds Status: 402 Payment Required Updated: 2026-10-14 ## When to use it Use 402 with an Insufficient Funds error when the client is authenticated and authorized to perform the action, but the account backing the request cannot cover its cost. This covers a declined card, an exhausted prepaid balance, a spent credit allocation, or a wallet that would go negative if the operation completed. The request is well formed and would succeed if the account were funded, so the client's correct next step is to add funds or update a payment method and retry the same request. RFC 9110 says only that 402 "is reserved for future use", so generic HTTP clients, proxies and libraries attach no defined semantics to it. 402 is still the established choice for payment failures (Stripe's API, for one, documents 402 as "Request Failed" for valid requests that fail, such as a declined card), but the status alone tells a client little: the problem `type` and its members are what say what happened and how to fix it. ## When not to use it Do not use this when the account is suspended, closed, or under review. The client cannot fix those by paying, so use `account-frozen` instead. Do not use this for plan or quota limits that are not monetary, such as rate limits (use `rate-limit-exceeded`), a plan's allowance for the billing period (use `quota-exceeded`) or a feature missing from the caller's token scopes (use `insufficient-scope`). ## Example response ```json { "type": "https://apiguide.dev/errors/insufficient-funds", "title": "Insufficient Funds", "status": 402, "detail": "The account balance of 4.20 USD is short of the 25.00 USD required for this charge.", "instance": "/v1/charges", "balance": "4.20", "required": "25.00", "currency": "USD", "topUpUrl": "https://billing.example.com/top-up" } ``` Report the shortfall in the same currency the client was charged in, and link to the page where they can resolve it. Never echo card numbers or payment credentials back in the error body. --- # Insufficient Scope > Use 403 with an Insufficient Scope error when the client's credentials (like an API token or OAuth access token) are valid and authenticated, but the token lacks the specific permissions or scopes needed to access the requested resource or perform the HTTP action. Source: https://apiguide.dev/errors/insufficient-scope Problem type URI: https://apiguide.dev/errors/insufficient-scope Status: 403 Forbidden Updated: 2026-10-14 ## When to use it Use 403 with an Insufficient Scope error when the client's credentials (like an API token or OAuth access token) are valid and authenticated, but the token lacks the specific permissions or scopes needed to access the requested resource or perform the HTTP action. A common example is a token generated with a `read` scope attempting to perform a `POST`, `PUT`, or `DELETE` request. ## When not to use it Do not use this if the client is unauthenticated (use `unauthorized` or 401). Do not use this if the token is expired (use `expired-authentication-token` / 401). If the token's scopes are sufficient but your own permission rules deny the action, such as a non-owner deleting a project, use `forbidden`. ## Example response ```json { "type": "https://apiguide.dev/errors/insufficient-scope", "title": "Insufficient Scope", "status": 403, "detail": "The token provided lacks the required 'leads:write' scope.", "instance": "/v1/leads" } ``` Include a `WWW-Authenticate` header naming the missing scope, per RFC 6750: ```http WWW-Authenticate: Bearer error="insufficient_scope", error_description="The request requires the 'leads:write' scope", scope="leads:write" ``` --- # Internal Server Error > Use 500 Internal Server Error when the application encounters an unexpected, unhandled exception or system failure that prevents it from fulfilling the request. Source: https://apiguide.dev/errors/internal-server-error Problem type URI: https://apiguide.dev/errors/internal-server-error Status: 500 Internal Server Error Updated: 2026-07-09 ## When to use it Use 500 Internal Server Error when the application encounters an unexpected, unhandled exception or system failure that prevents it from fulfilling the request. This code indicates a bug, database failure, or structural breakdown within the server code. In production environments, always sanitize this response to prevent leaking internal stack traces, class names, or environment variables to the outside world. ## When not to use it Do not use 500 for validation errors, permission failures, or normal domain logic branches (e.g. record not found). In those cases, use the appropriate 4xx code. Do not use 500 if you know the server is overloaded or down for maintenance (use 503 Service Unavailable). ## Example response ```json { "type": "https://apiguide.dev/errors/internal-server-error", "title": "Internal Server Error", "status": 500, "detail": "An unexpected error occurred while processing the request.", "instance": "/v1/leads" } ``` --- # Invalid Credentials > Use `401 Unauthorized` with an Invalid Credentials error when the client presents a credential pair to authenticate and the pair does not check out: a username and password that do not match, an API key ID with the wrong secret, or HTTP Basic credentials for an account that does not exist. Source: https://apiguide.dev/errors/invalid-credentials Problem type URI: https://apiguide.dev/errors/invalid-credentials Status: 401 Unauthorized Updated: 2026-10-17 ## When to use it Use [`401 Unauthorized`](/status-codes/401) with an Invalid Credentials error when the client presents a credential pair to authenticate and the pair does not check out: a username and password that do not match, an API key ID with the wrong secret, or HTTP Basic credentials for an account that does not exist. The request was well formed and the client clearly tried to authenticate; the credentials were simply wrong. This is narrower than `unauthorized`. That type covers any request without valid authentication, including no credentials at all. This one tells the client it did send credentials and they were rejected, so retrying with the same values will never work and the user needs to re-enter them. Return the same response whichever half of the pair was wrong. "No such user" and "wrong password" are different failures on your side, but telling the client which one occurred lets an attacker enumerate valid usernames or key IDs. Keep the response time the same too, by running the password hash check even when the account does not exist. RFC 9110 requires a 401 to carry a [`WWW-Authenticate`](/headers/www-authenticate) challenge for the scheme the client should use, such as `Basic realm="api"`. ## When not to use it Do not use it at an OAuth 2.0 token endpoint. RFC 6749 fixes that error format: wrong resource owner credentials are `invalid_grant` with 400, and failed client authentication is `invalid_client`, which must be 401 when the client authenticated with the [`Authorization`](/headers/authorization) header. Clients built against OAuth libraries expect that shape. Do not use it for bearer tokens on ordinary API requests. A token that has expired is `expired-authentication-token`, one that was revoked is `token-revoked`, and one you do not recognize at all is `unauthorized`. Do not use it when the credentials were right but a second factor is still needed. That is `mfa-required`. Reporting correct credentials as invalid sends the user into a password reset they do not need. Do not use it when the account behind valid credentials is suspended. That is `account-frozen` (403). Whether you reveal suspension before checking credentials is a security decision: checking credentials first means only the account holder learns the account is frozen. ## Example response ```http HTTP/1.1 401 Unauthorized Content-Type: application/problem+json WWW-Authenticate: Basic realm="api" { "type": "https://apiguide.dev/errors/invalid-credentials", "title": "Invalid Credentials", "status": 401, "detail": "The username or password is incorrect.", "instance": "/v1/sessions" } ``` Limit failed attempts per account and per source, and answer the excess with `rate-limit-exceeded` (429). Without a limit, an endpoint that returns this type is an online password-guessing service. --- # Invalid Pagination Cursor > Use 400 when the client sent a value that fails structural validation before any business logic runs. Source: https://apiguide.dev/errors/invalid-pagination-cursor Problem type URI: https://apiguide.dev/errors/invalid-pagination-cursor Status: 400 Bad Request Updated: 2026-10-14 ## When to use it Use 400 when the client sent a value that fails structural validation before any business logic runs. A cursor parameter that isn't valid base64, or that decodes to something other than the expected shape, belongs here. The key test: has the server been able to understand what the client is asking for at all? If not, it's 400. ## When not to use it If the cursor decodes fine and points to a real position, but that position is no longer valid because the underlying dataset changed, that's closer to 422 or even 410 depending on your API's semantics. Don't use 400 for a request the server understood but can't fulfill. ## Example response ```json { "type": "https://apiguide.dev/errors/invalid-pagination-cursor", "title": "Invalid Pagination Cursor", "status": 400, "detail": "The cursor parameter could not be decoded.", "instance": "/v1/leads?cursor=not-valid-base64" } ``` --- # Invalid Query Parameter > Use 400 Invalid Query Parameter when the query string is the problem. Source: https://apiguide.dev/errors/invalid-query-parameter Problem type URI: https://apiguide.dev/errors/invalid-query-parameter Status: 400 Bad Request Updated: 2026-10-09 ## When to use it Use 400 Invalid Query Parameter when the query string is the problem. The path resolves and the body, if there is one, is fine, but a parameter in the URL cannot be accepted. That covers four cases: - A parameter the endpoint does not support, such as `?region=emea` on an endpoint with no `region` filter. - A parameter name that breaks the API's naming rules, such as `?Sort=name` on an API whose parameter names are all lowercase. - An unsupported value for a known parameter, such as an `include` path the endpoint cannot expand or a `sort` field it cannot order by. - A filter value that cannot be used, such as `?filter[status]=archived` when `status` only accepts `open` or `closed`. JSON:API 1.1 makes 400 Bad Request mandatory for several of these. A server that does not support an include path, or does not support sorting by a requested field, MUST respond with 400, and so must a server that receives a query parameter whose name breaks the specification's naming rules or that it does not know how to process. That is why APIs built on JSON:API use 400 here, where others reach for 422. Tell the client which parameter failed. A JSON:API error object has `source.parameter` for exactly this. In an RFC 9457 response, add an extension member such as `parameter`, as the example below does, so a client can read the name without parsing `detail`. ## When not to use it Do not use it when the body is the problem. A body that cannot be parsed is `malformed-request-body`, and a body that parses but breaks the rules is `validation-failed`. Do not use it for a pagination cursor that cannot be decoded. That is `invalid-pagination-cursor`, which clients handle differently: the fix is usually to start again from the first page, not to edit the query. Do not use it when the path or resource does not exist. That is `resource-not-found` (404), not a query string problem. 400 and 422 are both defensible for query string errors. 400 says the server will not accept the request as sent; 422 says it understood the request but cannot act on the values. JSON:API settles the question for APIs that follow it. Outside JSON:API, pick one and use it on every endpoint. If your API already returns 422 for query semantics, keep doing that and use `unprocessable-query` instead of this type. Do not mix the two at random, because clients branch on the status code before they read `type`. If you want a split, make it a rule: 400 for a value the endpoint never accepts, 422 for a value that is valid on its own but cannot be satisfied against the current data, such as page 2 of a one page collection. ## Example response ```json { "type": "https://apiguide.dev/errors/invalid-query-parameter", "title": "Invalid Query Parameter", "status": 400, "detail": "The sort parameter does not support the field nickname. Supported fields are created_at, name and status.", "parameter": "sort", "instance": "/v1/leads?sort=nickname" } ``` The request that triggers this response asks to sort by a field the endpoint cannot order by: ```http GET /v1/leads?sort=nickname HTTP/1.1 Host: api.example.com Accept: application/json ``` To recover, the client should correct or remove the parameter named in `parameter` and send the request again. Resending it unchanged fails the same way, so do not retry it automatically. If the value came from user input, show the error to the user rather than silently dropping the parameter: a dropped filter returns a wider result set than the user asked for. --- # Invalid Signature > Use `401 Unauthorized` with an Invalid Signature error when a request carries the signature your endpoint requires, and that signature fails verification. Source: https://apiguide.dev/errors/invalid-signature Problem type URI: https://apiguide.dev/errors/invalid-signature Status: 401 Unauthorized Updated: 2026-10-17 ## When to use it Use [`401 Unauthorized`](/status-codes/401) with an Invalid Signature error when a request carries the signature your endpoint requires, and that signature fails verification. Typical causes: - The signature value does not match the signature base you reconstruct, because a covered component was changed in transit or the client built the base differently. - The `keyid` names a key you do not know, or one that has been revoked. - The `created` timestamp is outside your tolerance window, or `expires` has passed. - The `alg` parameter disagrees with the algorithm bound to the key. - The `nonce` has been seen before, so the request is a replay. This applies to [HTTP Message Signatures](/specifications/http-message-signatures) (RFC 9421) in the [`Signature`](/headers/signature) and [`Signature-Input`](/headers/signature-input) fields, and to the HMAC signatures webhook senders put in their own headers. The signature is the credential that authenticates the sender, and it is not valid, so 401 is the code. RFC 9421 leaves the choice to the application and notes that 401 or 403 could be appropriate when a signature is used for authentication. Pick 401, because the fix is a correct signature, not a different permission. RFC 9110 requires every 401 to carry a [`WWW-Authenticate`](/headers/www-authenticate) challenge. Send the one your signing profile documents. ## When not to use it Do not use it when there is no signature, or none that covers the components you require. That is `missing-signature`: verification never got started. Do not use it when the signature fields do not parse. That is a plain [`400 Bad Request`](/status-codes/400). Do not use it when the signature verifies but the body does not match its [`Content-Digest`](/headers/content-digest). The signature proves the digest was not changed; the digest check is what failed, which is `digest-mismatched-values`. Do not use it when the signature verifies and the authenticated caller is simply not allowed to do this. That is `forbidden` (403). ## Example response ```json { "type": "https://apiguide.dev/errors/invalid-signature", "title": "Invalid Signature", "status": 401, "detail": "The signature sig1 was created outside the allowed window of 300 seconds. Check the signer's clock and sign the request again.", "instance": "/v1/transfers", "signatureLabel": "sig1", "reason": "created_out_of_window" } ``` Say which check failed, with a stable `reason` a client can branch on, such as `created_out_of_window`, `unknown_key` or `verification_failed`. Do not say more than that. Never return the signature base you computed or the signature you expected: the first helps an attacker see exactly what you verified, and the second hands them a valid signature. Compare signatures in constant time, as the [webhook signatures guide](/guides/webhook-signatures) explains, so the response time does not leak what the body does not. --- # Length Required > Use 411 Length Required when the server refuses a request with content that does not declare its size in `Content-Length`. Source: https://apiguide.dev/errors/length-required Problem type URI: https://apiguide.dev/errors/length-required Status: 411 Length Required Updated: 2026-10-14 ## When to use it Use 411 Length Required when the server refuses a request with content that does not declare its size in [`Content-Length`](/headers/content-length). RFC 9110 defines it as a server that "refuses to accept the request without a defined Content-Length", and says the client "MAY repeat the request if it adds a valid Content-Length header field". In HTTP/1.1, content without `Content-Length` arrives with [`Transfer-Encoding: chunked`](/headers/transfer-encoding), so the server does not learn the size until the last chunk. RFC 9112 says a server MAY reject such a request with 411. The legitimate reason is that you need the size before reading the body: to reject an oversized upload immediately, or because a downstream component requires the length in advance. RFC 9112 describes exactly that case, services that answer chunked requests with 411 because they sit behind a gateway that needs the length and are "unable or unwilling to buffer the entire request". Name the header in the response, and say whether your endpoint accepts chunked uploads at all, so the client knows to set `Content-Length` and not try a different encoding. ## When not to use it Do not require `Content-Length` unless you need it. RFC 9112 tells clients to prefer `Content-Length` over chunked when the length is known in advance, but streaming clients often cannot know it, and a server that buffers or enforces a running byte limit can accept chunked bodies safely. Requiring the length shuts out streaming uploads for no gain. Do not use it when `Content-Length` is present and the body is larger than you allow. That is `payload-too-large` (413), and with `Content-Length` present you can return it before reading the body. Do not use it when `Content-Length` is present but invalid, such as a non-numeric value or conflicting values. RFC 9112 treats that as broken message framing: the server MUST respond with 400 and close the connection. That is a plain 400 from the HTTP server itself, and your application will usually never see the request. Do not use it when the client declared a length and then stopped sending before it arrived. That is `request-timeout` (408). Do not use it for requests with no content. RFC 9110 says a user agent SHOULD NOT send `Content-Length` on a request with no content when the method does not expect any, so a `GET` without it is correct, not a 411. ## Example response ```json { "type": "https://apiguide.dev/errors/length-required", "title": "Length Required", "status": 411, "detail": "Uploads to this endpoint must include a Content-Length header. Chunked transfer encoding is not accepted.", "instance": "/v1/documents/upload" } ``` The request that triggers it streams its body without declaring a length: ```http POST /v1/documents/upload HTTP/1.1 Host: api.example.com Content-Type: application/pdf Transfer-Encoding: chunked ``` To recover, the client should determine the size of the content, send it in `Content-Length`, drop `Transfer-Encoding`, and repeat the request. In HTTP/2 and HTTP/3, chunked transfer coding does not exist and the frames delimit the content, but `Content-Length` is still optional, so a server that requires it can return 411 there too. --- # Maintenance Mode > Use `503 Service Unavailable` with a Maintenance Mode error when you have taken the API, or part of it, out of service on purpose for planned work: a database migration, a data center move, a version upgrade that needs writes stopped. Source: https://apiguide.dev/errors/maintenance-mode Problem type URI: https://apiguide.dev/errors/maintenance-mode Status: 503 Service Unavailable Updated: 2026-10-17 ## When to use it Use [`503 Service Unavailable`](/status-codes/503) with a Maintenance Mode error when you have taken the API, or part of it, out of service on purpose for planned work: a database migration, a data center move, a version upgrade that needs writes stopped. RFC 9110 names scheduled maintenance as one of the two reasons for 503, alongside temporary overload. This is more specific than `service-unavailable`, which covers any temporary inability to serve, including an overload you did not plan. Planned maintenance has a known end, and that is what makes it worth its own type: the client can schedule its retry for the end of the window, show users an honest message, and pause background jobs, rather than backing off blindly. Always send [`Retry-After`](/headers/retry-after). RFC 9110 makes it optional on a 503, but for planned work you know the answer, and an HTTP-date set to the end of the window is the most useful value you can give. Repeat the window in the body so it reaches clients that do not read headers. A partial maintenance mode works the same way. If the API stays readable while writes are paused, answer the reads normally and the writes with this type. Say which operations are affected, so the client does not conclude the whole API is down. ## When not to use it Do not use it for unplanned outages or overload. You do not know when those end, and claiming a maintenance window you never scheduled misleads clients into retrying at the wrong time. That is `service-unavailable`. Do not use it for a feature that is switched off for one account or plan. That is `feature-disabled` (403), and it is not going to resolve on its own at the end of a window. Do not use it when your server is up and an upstream it depends on is down for its own maintenance. If you are acting as a gateway, that is `bad-gateway` (502) or `gateway-timeout` (504). If your API is the product and the upstream is an implementation detail, use `service-unavailable` and do not blame the third party in the response. Do not let a [health check](/guides/health-checks) endpoint return this type to your own load balancer during maintenance unless you mean for the instance to be pulled from rotation. Decide which endpoints stay up and say so in your runbook. ## Example response ```http HTTP/1.1 503 Service Unavailable Content-Type: application/problem+json Retry-After: Sat, 17 Oct 2026 06:00:00 GMT { "type": "https://apiguide.dev/errors/maintenance-mode", "title": "Maintenance Mode", "status": 503, "detail": "Writes are paused for scheduled database maintenance until 06:00 UTC. Reads are unaffected.", "instance": "/v1/orders", "maintenanceStartedAt": "2026-10-17T04:00:00Z", "maintenanceEndsAt": "2026-10-17T06:00:00Z", "statusPage": "https://status.example.com/incidents/2026-10-17-db" } ``` Announce the window before it starts, on a status page and through whatever channel your integrators read. A maintenance window clients only learn about from a 503 is an outage with better paperwork. --- # Malformed Request Body > Use 400 with a Malformed Request Body error when the server cannot parse the payload sent in the HTTP request body. Source: https://apiguide.dev/errors/malformed-request-body Problem type URI: https://apiguide.dev/errors/malformed-request-body Status: 400 Bad Request Updated: 2026-09-24 ## When to use it Use 400 with a Malformed Request Body error when the server cannot parse the payload sent in the HTTP request body. This occurs at the syntax level, for example if the client sends invalid JSON (such as missing a closing brace, trailing commas, or unescaped characters). Since the server cannot read the payload, it cannot run any validation or domain logic. ## When not to use it Do not use this error if the JSON itself is well-formed, but lacks required fields or contains invalid parameter values. In those cases, use `validation-failed` or `unprocessable-query`. ## Example response ```json { "type": "https://apiguide.dev/errors/malformed-request-body", "title": "Malformed Request Body", "status": 400, "detail": "The request body could not be parsed as valid JSON: Syntax error.", "instance": "/v1/leads" } ``` --- # Method Not Allowed > Use 405 Method Not Allowed when the HTTP request URI matches a valid path in your routing table, but the specific HTTP method used (e.g. `POST`, `PUT`, `DELETE`) is not supported by that endpoint. Source: https://apiguide.dev/errors/method-not-allowed Problem type URI: https://apiguide.dev/errors/method-not-allowed Status: 405 Method Not Allowed Updated: 2026-10-14 ## When to use it Use 405 Method Not Allowed when the HTTP request URI matches a valid path in your routing table, but the specific HTTP method used (e.g. `POST`, `PUT`, `DELETE`) is not supported by that endpoint. HTTP specifications require that a 405 response must include an `Allow` header listing the valid HTTP methods for the requested resource (e.g. `Allow: GET, HEAD`). ## When not to use it Do not use 405 if the URI itself does not exist in the routing table (use `resource-not-found` / 404 instead). If the server does not recognize or implement the method for any resource at all, use `not-implemented` (501). ## Example response ```json { "type": "https://apiguide.dev/errors/method-not-allowed", "title": "Method Not Allowed", "status": 405, "detail": "The POST method is not supported for this endpoint. Supported methods: GET, HEAD.", "instance": "/v1/leads" } ``` Together with the response, send the `Allow` header: ```http Allow: GET, HEAD ``` --- # MFA Required > Use `401 Unauthorized` with an MFA Required error when the caller is authenticated, but not strongly or recently enough for this operation, and must complete multi-factor authentication before it can proceed. Source: https://apiguide.dev/errors/mfa-required Problem type URI: https://apiguide.dev/errors/mfa-required Status: 401 Unauthorized Updated: 2026-10-17 ## When to use it Use [`401 Unauthorized`](/status-codes/401) with an MFA Required error when the caller is authenticated, but not strongly or recently enough for this operation, and must complete multi-factor authentication before it can proceed. Common triggers are a sensitive action, such as changing payout details, deleting an organization or creating an API key, attempted on a session that signed in with a password alone, or on one whose last MFA check is too old for your policy. Use 401, not 403. The caller can fix this by authenticating again, more strongly, and that is what 401 means: the request lacks credentials that are sufficient for the target resource. 403 means authenticating again will not help, which is the opposite of what you want the client to do. For OAuth 2.0 resource servers this is step-up authentication, standardized in RFC 9470. It defines the `insufficient_user_authentication` error code for the Bearer [`WWW-Authenticate`](/headers/www-authenticate) challenge, meaning the authentication event behind the access token does not meet the resource's requirements, and its examples use 401. Two parameters say what is needed: `acr_values`, a space-separated list of acceptable authentication context class references, and `max_age`, the number of seconds allowed since the user last actively authenticated. The client takes those to the authorization server, gets a new token, and retries. ## When not to use it Do not use it when the user has not enrolled a second factor and your policy requires one. Re-authenticating cannot help until they enroll, so that is `forbidden` (403), with a `detail` pointing at enrollment. Do not use it when the token lacks an OAuth scope. That is `insufficient-scope` (403). RFC 9470 notes that a challenge can carry `scope` alongside `acr_values` when both are missing, but a scope problem on its own is not an authentication-strength problem. Do not use it during an interactive login flow to say "now enter your code". That is a step in your sign-in protocol, not an error on an API call, and modeling it as one makes every client treat a normal login as a failure. Do not use it in place of `invalid-credentials`. If the password was wrong, say so; asking for a second factor after a wrong password tells an attacker the password was right. ## Example response ```http HTTP/1.1 401 Unauthorized Content-Type: application/problem+json WWW-Authenticate: Bearer error="insufficient_user_authentication", acr_values="urn:example:acr:mfa", max_age="300" { "type": "https://apiguide.dev/errors/mfa-required", "title": "MFA Required", "status": 401, "detail": "Changing payout details requires multi-factor authentication within the last 5 minutes. Re-authenticate with a second factor and retry.", "instance": "/v1/payout-methods", "acrValues": ["urn:example:acr:mfa"], "maxAge": 300 } ``` `acr_values` are defined by your authorization server, not by RFC 9470, so publish the ones you use. Put the requirement in the problem body as well as the challenge, because many HTTP clients make response headers awkward to reach and the body is what ends up in logs. --- # Misdirected Request > Use `421 Misdirected Request` when a request reached a server that cannot give an authoritative response for its target URI. Source: https://apiguide.dev/errors/misdirected-request Problem type URI: https://apiguide.dev/errors/misdirected-request Status: 421 Misdirected Request Updated: 2026-10-17 ## When to use it Use [`421 Misdirected Request`](/status-codes/421) when a request reached a server that cannot give an authoritative response for its target URI. RFC 9110 says an origin server, or a gateway acting for it, sends 421 to reject a target URI that does not match an origin the server is configured for, or that does not match the connection the request arrived on. The common cause is connection reuse. HTTP/2 and HTTP/3 clients may send requests for several hostnames over one connection when those hostnames resolve to the same server and share a TLS certificate. If the certificate covers `*.example.com` but `billing.example.com` is served by a different cluster, a request for it can land on the wrong one. 421 tells the client to open a new connection. The other is a mismatch between the TLS server name and the [`Host`](/headers/host) or `:authority` the request names, which some servers reject deliberately so that one tenant's hostname cannot be reached through another tenant's TLS session. RFC 9110 says a client that receives 421 MAY retry the request over a different connection, "whether or not the request method is idempotent". That is unusual, and it is the point: the server is promising it did nothing with the request. ## When not to use it Do not use it when the host is right and the path does not exist. That is `resource-not-found` (404). 421 is about the wrong server, not the wrong resource. Do not use it unless you are certain the request was not processed. A client may resend a [`POST`](/methods/post) after a 421 with no idempotency protection, so returning it after doing any work invites a duplicate. Do not generate it from a proxy. RFC 9110 says "A proxy MUST NOT generate a 421 response." A proxy that cannot reach the right upstream has a gateway problem, which is `bad-gateway` (502). Do not use it to send a client to a different hostname, such as a regional endpoint. A 421 retry goes to the same URI on a new connection, so it will not carry the client anywhere new. Use a redirect, or a problem type that names the correct base URL. ## Example response ```http HTTP/1.1 421 Misdirected Request Content-Type: application/problem+json { "type": "https://apiguide.dev/errors/misdirected-request", "title": "Misdirected Request", "status": 421, "detail": "This server is not configured to serve billing.example.com. Retry the request on a new connection.", "instance": "/v1/invoices" } ``` Most HTTP/2 and HTTP/3 clients handle 421 by retrying on a fresh connection without surfacing it, so this body is mainly for logs and for clients that do not. If you see 421s in volume, the fix is usually at the edge: separate certificates for hostnames served by different backends, or the HTTP/2 `ORIGIN` frame from RFC 8336, which tells clients which origins a connection actually serves. --- # Missing Signature > Use `401 Unauthorized` with a Missing Signature error when an endpoint requires signed requests and the request does not carry the signature it needs. Source: https://apiguide.dev/errors/missing-signature Problem type URI: https://apiguide.dev/errors/missing-signature Status: 401 Unauthorized Updated: 2026-10-17 ## When to use it Use [`401 Unauthorized`](/status-codes/401) with a Missing Signature error when an endpoint requires signed requests and the request does not carry the signature it needs. That covers three cases: no [`Signature`](/headers/signature) and [`Signature-Input`](/headers/signature-input) fields at all, signatures present but none from a key you accept for this caller, and a signature that does not cover the components your profile requires, such as one over `@method` and `@path` when you require `@target-uri` and `content-digest` as well. It applies equally to [HTTP Message Signatures](/specifications/http-message-signatures) (RFC 9421) and to the HMAC schemes most webhook senders use, described in the [webhook signatures guide](/guides/webhook-signatures). In both, the signature is how the receiver knows who sent the request, which is why 401 is the right code: the request lacks the credential that authenticates it. RFC 9421 leaves error handling to the application, and notes that 401 or 403 could be appropriate when a signature is used for authentication. RFC 9110 requires every 401 to carry a [`WWW-Authenticate`](/headers/www-authenticate) header with at least one challenge. RFC 9421 does not define an authentication scheme, so send the challenge your signing profile documents. For RFC 9421, also send `Accept-Signature`, which RFC 9421 defines for exactly this: in a response, it tells the client how to sign its next request. ## When not to use it Do not use it when a signature is present, covers the right components and comes from a known key, but fails to verify. That is `invalid-signature`. The split matters to the client: a missing signature is a configuration or integration bug, while an invalid one can be a clock problem, a body that changed in transit, or an attack. Do not use it when the signature fields are present but do not parse as Structured Fields. That is a plain [`400 Bad Request`](/status-codes/400): the client sent something malformed, not something unsigned. Do not use it when the request has no credentials of any kind on an endpoint where a signature is optional. If signing is optional, an unsigned request is either accepted or fails for another reason, such as a missing token, which is `unauthorized`. Do not use it when the problem is the body digest rather than the signature. A [`Content-Digest`](/headers/content-digest) that does not match the body is `digest-mismatched-values`, even if the signature covering that field verifies. ## Example response ```http HTTP/1.1 401 Unauthorized Content-Type: application/problem+json WWW-Authenticate: Signature realm="payments-api" Accept-Signature: sig1=("@method" "@target-uri" "content-digest");created;keyid="client-key-2026" { "type": "https://apiguide.dev/errors/missing-signature", "title": "Missing Signature", "status": 401, "detail": "Requests to this endpoint must be signed with HTTP Message Signatures, covering @method, @target-uri and content-digest.", "instance": "/v1/transfers", "requiredComponents": ["@method", "@target-uri", "content-digest"] } ``` `Signature` here is not a registered authentication scheme: it stands for whatever name your signing profile documents. The [request signing guide](/guides/request-signing) covers choosing the components to require. A webhook receiver is the server in this exchange, so it returns this response to the sender. Most senders treat any non-2xx response as a failed delivery and retry, so the body mostly ends up in the sender's delivery logs. Make the `detail` useful to whoever reads those. --- # Not Acceptable > Use 406 Not Acceptable when the client asks, through proactive content negotiation, for a representation the server is unable to produce. Source: https://apiguide.dev/errors/not-acceptable Problem type URI: https://apiguide.dev/errors/not-acceptable Status: 406 Not Acceptable Updated: 2026-09-24 ## When to use it Use 406 Not Acceptable when the client asks, through proactive content negotiation, for a representation the server is unable to produce. The client expresses its preferences with headers like `Accept`, `Accept-Language`, `Accept-Encoding`, or `Accept-Charset`, and when none of the acceptable options overlaps with what the server can generate, 406 signals that no compatible representation exists. A common example is an API that only serializes JSON receiving `Accept: application/xml`. Because the server has nothing that satisfies the request's stated constraints, it returns 406 rather than sending a JSON body the client explicitly declared it would not accept. In practice many APIs choose to ignore an unsatisfiable `Accept` and return their default representation anyway, so reserve 406 for cases where strict negotiation is a deliberate contract. ## When not to use it Do not confuse 406 with `unsupported-media-type` (415). The two sit on opposite sides of the exchange: 406 is about the response the client is willing to receive (the `Accept` header), while 415 is about the request body the server is unwilling to consume (the `Content-Type` header). If a client uploads a payload in a format the server cannot parse, that is 415, not 406. Do not use 406 for content that is negotiable but simply invalid. Validation and query problems belong to `unprocessable-query` and 422. ## Example response ```json { "type": "https://apiguide.dev/errors/not-acceptable", "title": "Not Acceptable", "status": 406, "detail": "This endpoint can only produce application/json, which does not match the Accept header.", "instance": "/v1/reports/quarterly" } ``` The offending request declares an `Accept` header the server cannot satisfy: ```http GET /v1/reports/quarterly HTTP/1.1 Host: api.example.com Accept: application/xml ``` To resolve it, the client should send an `Accept` value the server supports (for example `Accept: application/json`) or omit the header to receive the endpoint's default representation. --- # Not Implemented > Use 501 Not Implemented when the server does not recognize the request method and cannot support it on any resource. Source: https://apiguide.dev/errors/not-implemented Problem type URI: https://apiguide.dev/errors/not-implemented Status: 501 Not Implemented Updated: 2026-10-14 ## When to use it Use 501 Not Implemented when the server does not recognize the request method and cannot support it on any resource. RFC 9110 defines 501 as a server that "does not support the functionality required to fulfill the request", names the unrecognized method as the case it is meant for, and says an origin server that receives a method that is "unrecognized or not implemented SHOULD respond with the 501 (Not Implemented) status code". The test is server-wide. If no route on the server handles the method, it is 501. A typical API example is a client sending [`QUERY`](/methods/query) (RFC 10008) to a server that has not implemented it, or a WebDAV method such as [`PROPFIND`](/methods/propfind) to an API that has never supported WebDAV. RFC 9112 gives two more cases for HTTP/1.1. A server that receives a method longer than any it implements SHOULD respond with 501, and so should a server that receives a request with a transfer coding it does not understand. RFC 9110 requires every general-purpose server to support [`GET`](/methods/get) and [`HEAD`](/methods/head), so never return 501 for either. ## When not to use it Do not use it when the server implements the method but this resource does not accept it. That is `method-not-allowed` (405). RFC 9110 draws the line exactly: a method that is "recognized and implemented, but not allowed for the target resource" gets 405. `DELETE` on a read-only collection is 405 when other routes accept `DELETE`, even if this one never will. The [`Allow`](/headers/allow) header follows the same split. RFC 9110 says an origin server MUST send `Allow` in a 405 response and MAY send it in any other. A 405 without `Allow` breaks the spec. On a 501 it is optional, and it describes only the target resource, so it does not tell the client which methods the server recognizes overall. Do not use 501 for an endpoint you have not built yet. Until the route exists, it is `resource-not-found` (404). A 501 on a planned route tells clients the server does not understand the method, which is not true. Do not use it for an unsupported option within a request the server otherwise understands, such as a filter or sort field the endpoint does not offer. That is `invalid-query-parameter` (400): the client can fix it, and a 5xx tells generic clients and dashboards that the server is at fault. ## Example response ```json { "type": "https://apiguide.dev/errors/not-implemented", "title": "Not Implemented", "status": 501, "detail": "This server does not implement the QUERY method. Send the query as a POST to /v1/leads/search instead.", "instance": "/v1/leads" } ``` The request that triggers it uses a method no route on the server handles: ```http QUERY /v1/leads HTTP/1.1 Host: api.example.com Content-Type: application/json ``` 501 is a 5xx, and many retry policies retry every 5xx. Retrying a 501 never helps, so clients should treat it as permanent until the server changes. RFC 9110 also makes 501 heuristically cacheable, so a cache may reuse it without explicit freshness information. Send `Cache-Control` if you plan to add the method soon. --- # Oblivious HTTP Key Configuration Not Acceptable > Use 400 with this type when you run an Oblivious Gateway Resource under RFC 9458, Oblivious HTTP, and an Encapsulated Request was made with a key configuration you no longer accept or never issued: an unknown key identifier, a rotated-out key, or an unsupported HPKE suite. Source: https://apiguide.dev/errors/ohttp-key-not-acceptable Problem type URI: https://iana.org/assignments/http-problem-types#ohttp-key Alias: https://apiguide.dev/errors/ohttp-key-not-acceptable (registered with IANA; send the registered URI) Status: 400 Bad Request Updated: 2026-10-17 ## When to use it Use 400 with this type when you run an Oblivious Gateway Resource under RFC 9458, Oblivious HTTP, and an Encapsulated Request was made with a key configuration you no longer accept or never issued: an unknown key identifier, a rotated-out key, or an unsupported HPKE suite. The type is defined in Section 5.3 of RFC 9458 and registered in the IANA HTTP Problem Types registry as `https://iana.org/assignments/http-problem-types#ohttp-key`. Send that URI as the `type`. It is the signal for the client to fetch a fresh key configuration, served as `application/ohttp-keys`, and try again. Keep it short. The response cannot be encapsulated, because the gateway could not decrypt the request and so has no context to encrypt the reply with. It travels back in the clear through the Oblivious Relay Resource, so put nothing in it you would not show the relay. ## When not to use it Outside Oblivious HTTP, do not use it at all. It is a narrow, registered type with one meaning, and borrowing it for a general "wrong key" error, such as an unknown signing key on a webhook, misleads any client that recognizes it. Do not use it when the request decrypts but its `Date` falls outside your replay window. That is `date-not-acceptable`. Do not rely on clients receiving it. RFC 9458 says a client cannot count on a gateway sending this type, and may ignore unencapsulated responses because the relay could have altered them. Clients usually refresh key configurations on a schedule, or after any unencapsulated error, rather than waiting for this signal. ## Example response ```http HTTP/1.1 400 Bad Request Content-Type: application/problem+json ``` ```json { "type": "https://iana.org/assignments/http-problem-types#ohttp-key", "title": "Oblivious HTTP key configuration not acceptable", "status": 400 } ``` --- # Payload Too Large > Use 413 Content Too Large (formerly "Payload Too Large") when the client sends a request body (often a file upload or bulk records batch) that exceeds the maximum size limit configured on the server or application. Source: https://apiguide.dev/errors/payload-too-large Problem type URI: https://apiguide.dev/errors/payload-too-large Status: 413 Content Too Large Updated: 2026-10-14 ## When to use it Use 413 Content Too Large (formerly "Payload Too Large") when the client sends a request body (often a file upload or bulk records batch) that exceeds the maximum size limit configured on the server or application. This informs the client that their request was rejected solely because of its size, and that they should slice the request into smaller chunks or compress the payload. ## When not to use it Do not use 413 if the payload size is within bounds, but contains too many database records or relations that violate business constraints. In those cases, use `validation-failed` or `unprocessable-query`. ## Example response ```json { "type": "https://apiguide.dev/errors/payload-too-large", "title": "Payload Too Large", "status": 413, "detail": "The request body size of 24.5 MB exceeds the limit of 10 MB.", "instance": "/v1/documents/upload" } ``` --- # Precondition Failed > Use 412 Precondition Failed when the client attaches a conditional header such as `If-Match` or `If-Unmodified-Since`, and the condition evaluates to false because the resource changed on the server since the client last saw it. Source: https://apiguide.dev/errors/precondition-failed Problem type URI: https://apiguide.dev/errors/precondition-failed Status: 412 Precondition Failed Updated: 2026-10-14 ## When to use it Use 412 Precondition Failed when the client attaches a conditional header such as `If-Match` or [`If-Unmodified-Since`](/headers/if-unmodified-since), and the condition evaluates to false because the resource changed on the server since the client last saw it. This is the backbone of optimistic concurrency control: the client sends the ETag it believes is current, and the server rejects the write if that ETag no longer matches the live representation. The typical flow is a read followed by a write. A `GET` returns the resource along with an `ETag`, the client edits its local copy, then sends a `PUT` or `PATCH` carrying `If-Match: ""`. If another actor updated the resource in the meantime, the stored ETag differs, the precondition fails, and the server responds with 412 rather than silently overwriting the newer state. ## When not to use it Do not use 412 when the request carries no conditional headers. An unconditional write that hits a version mismatch should surface as `resource-conflict` (409) instead. Do not use 412 for missing `If-Match` on a resource that requires it; that is a 428 Precondition Required. Reserve 412 strictly for the case where a precondition was supplied and demonstrably did not hold. If you need to communicate that the client is holding an outdated snapshot, pair it with the guidance in `stale-resource-version`. ## Example response ```json { "type": "https://apiguide.dev/errors/precondition-failed", "title": "Precondition Failed", "status": 412, "detail": "The resource has been modified since you last fetched it. Re-fetch and retry with the current ETag.", "instance": "/v1/documents/8123" } ``` The client's request that triggers this response includes the conditional header holding the ETag it expects to still be current: ```http PATCH /v1/documents/8123 HTTP/1.1 Host: api.example.com If-Match: "a1b2c3d4" Content-Type: application/json ``` To recover, the client should re-`GET` the resource, read the new `ETag` from the response, reconcile its changes against the updated state, and retry the write with the fresh value in `If-Match`. --- # Precondition Required > Use 428 Precondition Required, defined in RFC 6585, when the server requires a state-changing request to be conditional and the client sent it without any precondition. Source: https://apiguide.dev/errors/precondition-required Problem type URI: https://apiguide.dev/errors/precondition-required Status: 428 Precondition Required Updated: 2026-10-14 ## When to use it Use 428 Precondition Required, defined in RFC 6585, when the server requires a state-changing request to be conditional and the client sent it without any precondition. In practice that means a `PUT`, `PATCH` or `DELETE` that arrives with neither `If-Match` nor [`If-Unmodified-Since`](/headers/if-unmodified-since) on a resource where the server enforces optimistic concurrency control. The point is to prevent lost updates. Without a precondition the server has no way to tell whether the client saw the current state before writing, so an unconditional write would silently overwrite whatever another actor changed in the meantime. Rejecting it with 428 forces the client to read the resource, take its `ETag`, and state which version it intends to replace. RFC 6585 asks that the response explain how to resubmit the request successfully, which is what the `detail` member is for. ## When not to use it Do not use 428 when the client did send a precondition and it did not hold. That is `precondition-failed` (412): the `If-Match` value no longer matches the current `ETag`, or the resource changed after the `If-Unmodified-Since` date. 428 is only for the case where the precondition is absent. Do not use 428 when the client sent a version in the request body, such as a `version` integer, and that version is out of date. That is `stale-resource-version` (409). If your API carries versions in the body rather than in headers, a missing version field is a validation problem and belongs in `validation-failed`, not 428. Do not use 428 on endpoints that accept unconditional writes, and do not return it for safe methods such as `GET`. Do not start requiring preconditions on an existing endpoint without warning, either: every client that writes without `If-Match` today will begin failing on the next request, so treat the change as a breaking one and announce it before you enforce it. ## Example response ```json { "type": "https://apiguide.dev/errors/precondition-required", "title": "Precondition Required", "status": 428, "detail": "Updates to this resource must be conditional. Fetch the resource, read its ETag, and retry the request with that value in the If-Match header.", "instance": "/v1/documents/8123" } ``` The request that triggers this response is a write with no conditional header at all: ```http PATCH /v1/documents/8123 HTTP/1.1 Host: api.example.com Content-Type: application/json ``` To recover, the client should `GET` the resource, read the `ETag` from the response, and retry the write with `If-Match: ""`. If the resource changes again before the retry lands, the server responds with `precondition-failed` (412) and the client repeats the read. RFC 6585 also states that a 428 response must not be stored by a cache. --- # Quota Exceeded > Use 429 with a Quota Exceeded error when the client has used up the allowance on its plan for the current billing period, such as 100,000 requests a month or 50 GB of exports per cycle, and further requests are refused until the period resets or the plan changes. Source: https://apiguide.dev/errors/quota-exceeded Problem type URI: https://apiguide.dev/errors/quota-exceeded Status: 429 Too Many Requests Updated: 2026-10-14 ## When to use it Use 429 with a Quota Exceeded error when the client has used up the allowance on its plan for the current billing period, such as 100,000 requests a month or 50 GB of exports per cycle, and further requests are refused until the period resets or the plan changes. Some APIs return 403 for this. Use 429, for three reasons: - **The definition covers it.** RFC 6585 defines 429 as the user having "sent too many requests in a given amount of time". A billing period is a given amount of time; it is just longer than a minute. - **It tells the client when to come back.** RFC 6585 says a 429 MAY carry [`Retry-After`](/headers/retry-after), and an HTTP-date set to the start of the next period gives the exact time the allowance resets. A 403 has no such convention. - **403 says something else.** RFC 9110 says a client receiving 403 "SHOULD NOT automatically repeat the request with the same credentials", and generic clients treat it as a permissions failure. A quota is not a permissions failure. The same credentials will work again on the first day of the next period. The RateLimit header fields Internet-Draft (`draft-ietf-httpapi-ratelimit-headers`, revision 11 at the time of writing) agrees: it proposes a `quota-exceeded` problem type with 429 as its recommended status code. It is still a draft and the type is not yet in the IANA HTTP Problem Types registry, so use this page's type URI today. Advertise the allowance before the client hits it. The draft's [`RateLimit-Policy`](/headers/ratelimit-policy) field describes a policy with `q` (the quota), `w` (the window in seconds) and `qu` (the unit: `requests`, `content-bytes` or `concurrent-requests`, defaulting to `requests`). The [`RateLimit`](/headers/ratelimit) field reports what is left with `r` and the seconds until the window resets with `t`. A billing period does not map exactly onto a fixed `w`, because calendar months vary in length, so treat `w` as an approximation and rely on `t` and `Retry-After` for the exact reset. ## When not to use it Do not use it for a short rolling or fixed window that exists to protect capacity, such as 100 requests a minute. That is `rate-limit-exceeded`. The difference matters to the client: a rate limit means "slow down and retry in seconds", so retry with backoff; a quota means "you are done until the reset or until you upgrade", so stop and tell a human. Both are 429, and the `type` is what lets a client tell them apart. Do not use it when the request needs money the account does not have, such as a prepaid balance or credits that have run out. That is `insufficient-funds` (402): the fix is a payment, not waiting for a reset. Do not use it when the plan does not include the feature at all. No amount of waiting fixes that, so it is `forbidden` (403). Do not use it when the account itself is suspended; that is `account-frozen`. Do not move an existing API from 403 to 429 without warning. Clients that branch on 403 will start retrying, or stop recognizing the condition. Treat the change as a breaking one. ## Example response ```json { "type": "https://apiguide.dev/errors/quota-exceeded", "title": "Quota Exceeded", "status": 429, "detail": "This account has used all 100000 requests included in its plan for the period ending 2026-10-31. The allowance resets on 2026-11-01, or you can upgrade now.", "instance": "/v1/leads", "violatedPolicies": ["monthly"], "resetsAt": "2026-11-01T00:00:00Z", "upgradeUrl": "https://billing.example.com/plans" } ``` Send the reset time and the policy in headers, not only in the body: ```http HTTP/1.1 429 Too Many Requests Content-Type: application/problem+json Retry-After: Sun, 01 Nov 2026 00:00:00 GMT RateLimit-Policy: "burst";q=100;w=60, "monthly";q=100000;w=2592000 RateLimit: "monthly";r=0;t=1468800 ``` Here `t` is the 17 days from 2026-10-15T00:00:00Z to the reset. The draft says that when a response carries both fields, `Retry-After` takes precedence. RFC 6585 says a 429 MUST NOT be stored by a cache. The `violatedPolicies` member mirrors the draft's `violated-policies` extension; if you adopt the draft's own type later, switch to its member name at the same time. --- # Range Not Satisfiable > Use 416 Range Not Satisfiable when a client sends a `Range` header for part of a representation and none of the ranges it asked for can be served. Source: https://apiguide.dev/errors/range-not-satisfiable Problem type URI: https://apiguide.dev/errors/range-not-satisfiable Status: 416 Range Not Satisfiable Updated: 2026-10-14 ## When to use it Use 416 Range Not Satisfiable when a client sends a [`Range`](/headers/range) header for part of a representation and none of the ranges it asked for can be served. RFC 9110 defines 416 for a range set rejected "either because none of the requested ranges are satisfiable or because the client has requested an excessive number of small or overlapping ranges (a potential denial of service attack)". For byte ranges on a `GET`, RFC 9110 says a range is satisfiable if it is an int-range whose first position is less than the current length of the representation, or a suffix range with a non-zero length. So for a 10,000-byte file, `bytes=10000-` and `bytes=20000-29999` cannot be satisfied. `bytes=9500-20000` can: the server cuts the range at the end of the file and serves bytes 9500 to 9999. The common API case is a resumable download. The client stored 47,022 bytes, the download was in fact complete, and it asks to resume from byte 47,022. Nothing remains to send, so the answer is 416. RFC 9110 says a server sending 416 for a byte-range request SHOULD include [`Content-Range`](/headers/content-range) with an unsatisfied-range value, `bytes */`, giving the current length of the selected representation. That one header is what lets the client recover: if the length matches what it already holds, the download is done; if not, the file has changed and it should start again. ## When not to use it Do not use it for a `Range` header your server does not support or cannot parse. RFC 9110 lets a server ignore `Range` entirely, and requires an origin server to ignore one with a range unit it does not understand. Answer with 200 and the full representation. Many servers do this for every range request, which is why RFC 9110 warns that clients "cannot depend on receiving a 416". Do not use it for a `Range` header on a method other than `GET`. RFC 9110 says a server MUST ignore a `Range` header on a method for which range handling is not defined, and `GET` is the only one it defines. Do not use it for page-based or cursor pagination that goes past the end of a collection. That is not an HTTP range request: return an empty page, or use `unprocessable-query` or `invalid-query-parameter` if your API treats it as an error. Do not use it when the client's [`If-Range`](/headers/if-range) validator no longer matches. RFC 9110 handles that case by sending the full representation with 200, not an error. And if the client sent `If-Match` and the representation changed, that is `precondition-failed` (412). ## Example response ```http HTTP/1.1 416 Range Not Satisfiable Content-Range: bytes */47022 Content-Type: application/problem+json ``` ```json { "type": "https://apiguide.dev/errors/range-not-satisfiable", "title": "Range Not Satisfiable", "status": 416, "detail": "The requested range starts at byte 47022, but the file is 47022 bytes long.", "instance": "/v1/exports/exp_3391/file" } ``` The request that triggers it asks to resume from the first byte past the end of the file: ```http GET /v1/exports/exp_3391/file HTTP/1.1 Host: api.example.com Range: bytes=47022- ``` The `Content-Range` header carries the information a client acts on, so send it even if you keep the body minimal. The body is optional; the header is not something you should leave out. --- # Rate Limit Exceeded > Use 429 when the client has sent more requests than your rate limiting policy allows within a given window. Source: https://apiguide.dev/errors/rate-limit-exceeded Problem type URI: https://apiguide.dev/errors/rate-limit-exceeded Status: 429 Too Many Requests Updated: 2026-10-14 ## When to use it Use 429 when the client has sent more requests than your rate limiting policy allows within a given window. The request itself is fine. The client just needs to slow down. This is one of the few error codes where the response body matters less than the headers. A well formed 429 tells the client exactly when it's safe to retry, via `Retry-After` and the [`RateLimit`](/headers/ratelimit) field, rather than leaving them to guess and hammer the endpoint again immediately. ## When not to use it 503 is for the server being overwhelmed or unavailable at a system level, not for a specific client exceeding their own quota. If your database connection pool is exhausted and every request is failing regardless of who sent it, that's 503. If one client is sending ten times their allotted requests per minute while everyone else is fine, that's 429. A common mistake is returning 429 for global outages just because it feels close enough. Keep it scoped to per client, per key, or per IP limits, not general capacity problems. If the client has used up its plan's allowance for the billing period, rather than exceeding a short window, use `quota-exceeded`. It is also 429, but the client should stop until the reset instead of backing off and retrying. ## Example response ```json { "type": "https://apiguide.dev/errors/rate-limit-exceeded", "title": "Rate Limit Exceeded", "status": 429, "detail": "Rate limit of 100 requests per minute exceeded for this API key.", "instance": "/v1/leads" } ``` Pair this with real headers on the response, not just the body: ```http Retry-After: 42 RateLimit-Policy: "per-minute";q=100;w=60 RateLimit: "per-minute";r=0;t=42 ``` --- # Request Header Fields Too Large > Use 431 Request Header Fields Too Large, defined in RFC 6585, when the server will not process the request because its header fields are too large. Source: https://apiguide.dev/errors/request-header-fields-too-large Problem type URI: https://apiguide.dev/errors/request-header-fields-too-large Status: 431 Request Header Fields Too Large Updated: 2026-10-14 ## When to use it Use 431 Request Header Fields Too Large, defined in RFC 6585, when the server will not process the request because its header fields are too large. RFC 6585 says it applies both "when the set of request header fields in total is too large, and when a single header field is at fault", and that the request "MAY be resubmitted after reducing the size of the request header fields". RFC 9110 makes rejection mandatory: a server that receives a header field line, field value or set of fields "larger than it wishes to process MUST respond with an appropriate 4xx (Client Error) status code". Silently ignoring an oversized field is not an option, because RFC 9110 notes that doing so increases exposure to request smuggling. 431 is the specific code for that 4xx. In APIs the usual causes are an [`Authorization`](/headers/authorization) header carrying a JWT stuffed with claims, such as every group or permission a user has, and a [`Cookie`](/headers/cookie) header that has grown as more cookies were set on the domain. Both grow over time with no change in client code, so a request that worked last month starts failing. When a single field is at fault, RFC 6585 says the response SHOULD name it. Do that: "header too large" with no field name sends the client hunting through every header it sends. ## When not to use it Do not use it when the request line is too long because of a long path or query string. That is `uri-too-long` (414). Do not use it for an oversized request body; that is `payload-too-large` (413). Do not use it when the token in `Authorization` is within size limits but invalid, expired or unrecognized. That is `unauthorized` (401). Size is checked before the token is even parsed, and the client's fix is different: a smaller token, not a new one. Expect to receive other codes for this condition from intermediaries. nginx, for example, returns 400 Bad Request when a single header field exceeds one `large_client_header_buffers` buffer, 8K by default. If you control the edge, configure it to return 431 with a problem body so clients get a consistent answer. ## Example response ```json { "type": "https://apiguide.dev/errors/request-header-fields-too-large", "title": "Request Header Fields Too Large", "status": 431, "detail": "The Authorization header is 12288 bytes. Individual header fields are limited to 8192 bytes.", "instance": "/v1/leads", "field": "Authorization", "maxFieldSize": 8192 } ``` RFC 6585 says a 431 response MUST NOT be stored by a cache. The lasting fix is usually on the issuing side, not the client. Keep access tokens small by referencing permissions rather than embedding them, and keep cookies scoped to the paths and domains that need them. Raising the server's header limit only postpones the next failure, and every proxy in the path has its own limit too. --- # Request Timeout > Use 408 Request Timeout when the server was prepared to receive a request but the client did not produce a complete one within the time the server was willing to wait. Source: https://apiguide.dev/errors/request-timeout Problem type URI: https://apiguide.dev/errors/request-timeout Status: 408 Request Timeout Updated: 2026-09-24 ## When to use it Use 408 Request Timeout when the server was prepared to receive a request but the client did not produce a complete one within the time the server was willing to wait. This is about the inbound half of the exchange: the connection opened, but the request line, headers, or body arrived too slowly, or never finished arriving, so the server gave up waiting and closed the idle connection. Typical triggers are a client that opens a socket and stalls before sending anything, a slow or interrupted upload that never reaches the declared `Content-Length`, or a keep-alive connection held open long past the server's idle threshold. Because the fault lies with the client's transmission rather than any server-side processing, 408 sits in the 4xx client-error range. ## When not to use it Do not use 408 for timeouts that happen while the server or an upstream dependency is doing work. If the request was fully received and a downstream service was too slow to answer, that is `gateway-timeout` (504); if the server itself is temporarily overloaded or down, use `service-unavailable` (503). The distinction is directional: 408 means the client was too slow to send, while 504 means an upstream was too slow to respond. Do not use 408 as a generic retry signal for backend latency. ## Example response ```json { "type": "https://apiguide.dev/errors/request-timeout", "title": "Request Timeout", "status": 408, "detail": "The server timed out waiting for the request to be completed.", "instance": "/v1/uploads" } ``` A server issuing 408 will normally signal that the connection is being torn down, since the incomplete request cannot be resumed: ```http HTTP/1.1 408 Request Timeout Connection: close Content-Type: application/problem+json ``` The `Connection: close` header tells the client not to reuse the socket. A client that sees 408 is free to open a fresh connection and send the request again, ideally after checking for slow uploads or an unstable network on its side. --- # Resource Conflict > Use 409 Resource Conflict when the request cannot be completed due to a conflict with the current state of the target resource. Source: https://apiguide.dev/errors/resource-conflict Problem type URI: https://apiguide.dev/errors/resource-conflict Status: 409 Conflict Updated: 2026-07-09 ## When to use it Use 409 Resource Conflict when the request cannot be completed due to a conflict with the current state of the target resource. The most common use case is a uniqueness constraint violation, such as attempting to register a user with an email address that is already active in the database. It is also appropriate when deleting a resource is blocked because it has active references or dependencies (e.g., trying to delete an organization that still contains active user profiles). ## When not to use it Do not use 409 for general input validation failures (like a malformed email address or a missing field). Use `validation-failed` (422) for those. Do not use 409 if the client is submitting concurrent requests with the same idempotency key; use `idempotency-key-conflict` instead. ## Example response ```json { "type": "https://apiguide.dev/errors/resource-conflict", "title": "Resource Conflict", "status": 409, "detail": "A user with the email address 'jane.doe@example.com' already exists.", "instance": "/v1/users" } ``` --- # Resource Locked > Use `423 Locked` when the client tries to change a resource that is locked, and the lock is an explicit state of that resource rather than a permission rule. Source: https://apiguide.dev/errors/resource-locked Problem type URI: https://apiguide.dev/errors/resource-locked Status: 423 Locked Updated: 2026-10-17 ## When to use it Use [`423 Locked`](/status-codes/423) when the client tries to change a resource that is locked, and the lock is an explicit state of that resource rather than a permission rule. RFC 4918, the WebDAV specification that defines the code, says it "means the source or destination resource of a method is locked". In an API this covers a few common designs: - **Edit locks.** A user has checked out a document for editing and holds a lock on it, and another caller tries to write. - **Processing locks.** A long-running job is working on the resource, such as an invoice being finalized or a dataset being reindexed, and writes are refused until it finishes. - **Holds.** A record is under a legal hold or an audit freeze and cannot be modified or deleted until the hold is released. Say who or what holds the lock and, if you know, when it will be released. The client can then wait, ask the holder to release it, or tell the user why their edit was refused. If the lock is short-lived, send [`Retry-After`](/headers/retry-after). ## When not to use it Do not use it when two writes collided and one lost because the resource changed underneath it. That is optimistic concurrency, not a lock: `precondition-failed` (412) when the client sent [`If-Match`](/headers/if-match), or `stale-resource-version` (409) when it sent a version in the body. Do not use it when the request conflicts with the resource's state in some other way, such as canceling an order that has already shipped. That is `resource-conflict` (409). 423 is specifically about a lock that someone holds and could release. Do not use it when the whole account is suspended. That is `account-frozen` (403). A lock applies to one resource; a frozen account blocks everything. Do not use it for reads unless the lock really does block reads. Most locks only block writes, and refusing a [`GET`](/methods/get) on a document someone else is editing is rarely what anyone wants. RFC 4918 says a 423 response SHOULD carry a precondition code such as `lock-token-submitted` or `no-conflicting-lock`. Those are WebDAV XML elements tied to its [`LOCK`](/methods/lock) method. Outside WebDAV, carry the equivalent information as extension members instead. ## Example response ```json { "type": "https://apiguide.dev/errors/resource-locked", "title": "Resource Locked", "status": 423, "detail": "Invoice inv_2041 is being finalized and cannot be edited until finalization completes.", "instance": "/v1/invoices/inv_2041", "lockedBy": "finalization", "lockedAt": "2026-10-17T09:30:12Z", "expectedReleaseAt": "2026-10-17T09:31:00Z" } ``` If clients can take locks themselves, return the lock's owner and expiry here, and make sure every lock expires. A lock with no timeout outlives the client that took it, and someone eventually has to clear it by hand. --- # Resource Not Found > Use 404 Resource Not Found when the requested URI does not match any route in the application routing table, or when a dynamic segment of the URI (such as an ID or UUID) refers to a resource database record that does not exist or has been deleted. Source: https://apiguide.dev/errors/resource-not-found Problem type URI: https://apiguide.dev/errors/resource-not-found Status: 404 Not Found Updated: 2026-10-14 ## When to use it Use 404 Resource Not Found when the requested URI does not match any route in the application routing table, or when a dynamic segment of the URI (such as an ID or UUID) refers to a resource database record that does not exist or has been deleted. A 404 is the definitive way to tell a client that the resource they are asking for does not exist. ## When not to use it Do not use 404 when the caller is not authenticated (use `unauthorized` / 401), or when the caller can see the resource but is not permitted to perform the action (use `forbidden` / 403). RFC 9110 does allow 404 in place of 403 when the caller should not learn that the resource exists at all, such as another tenant's records. If the resource was removed on purpose and you know it will not return, such as a sunset endpoint, use `gone` (410). ## Example response ```json { "type": "https://apiguide.dev/errors/resource-not-found", "title": "Resource Not Found", "status": 404, "detail": "No lead record found with ID 'lead_12345'.", "instance": "/v1/leads/lead_12345" } ``` --- # Service Unavailable > Use 503 Service Unavailable when the server is temporarily unable to process the request because it is overloaded or down for planned maintenance. Source: https://apiguide.dev/errors/service-unavailable Problem type URI: https://apiguide.dev/errors/service-unavailable Status: 503 Service Unavailable Updated: 2026-10-14 ## When to use it Use 503 Service Unavailable when the server is temporarily unable to process the request because it is overloaded or down for planned maintenance. Along with the 503 status, you should ideally include a `Retry-After` HTTP header indicating how long the client should wait before making another request (either in seconds, or as an HTTP-date timestamp). ## When not to use it Do not use 503 if the server encountered a code bug or unhandled database issue (use 500 Internal Server Error instead). Do not use this if an individual client is being rate-limited (use 429 Rate Limit Exceeded). ## Example response ```json { "type": "https://apiguide.dev/errors/service-unavailable", "title": "Service Unavailable", "status": 503, "detail": "The database is undergoing scheduled maintenance. Please try again later.", "instance": "/v1/leads" } ``` Include a header to notify the client when the service will be restored: ```http Retry-After: 300 ``` --- # Stale Resource Version > Use 409 Stale Resource Version when implementing optimistic concurrency control (OCC) and the client attempts to update or delete a resource using an outdated version indicator (such as an `ETag`, `version` integer, or `updated_at` timestamp). Source: https://apiguide.dev/errors/stale-resource-version Problem type URI: https://apiguide.dev/errors/stale-resource-version Status: 409 Conflict Updated: 2026-10-13 ## When to use it Use 409 Stale Resource Version when implementing optimistic concurrency control (OCC) and the client attempts to update or delete a resource using an outdated version indicator (such as an `ETag`, `version` integer, or `updated_at` timestamp). This indicates that another user or process has updated the resource since the client last fetched it, preventing the client from overwriting those changes (the "lost update" problem). ## When not to use it Do not use this for general data conflicts like duplicate unique values (use `resource-conflict`). Do not use this if the client is sending concurrent duplicate API calls using an idempotency key (use `idempotency-key-conflict`). ## Example response ```json { "type": "https://apiguide.dev/errors/stale-resource-version", "title": "Stale Resource Version", "status": 409, "detail": "The resource version '5' is stale. The resource has been updated by another process and is now version '6'.", "instance": "/v1/leads/lead_12345" } ``` Return the current `ETag` so the client can re-fetch, alongside the `If-Match` value it sent that was rejected: ```http ETag: "6" If-Match: "5" ``` --- # Tenant Suspended > Use `403 Forbidden` with a Tenant Suspended error when the caller's own credentials and account are fine, but the tenant the request targets, such as an organization, workspace or team, has been suspended. Source: https://apiguide.dev/errors/tenant-suspended Problem type URI: https://apiguide.dev/errors/tenant-suspended Status: 403 Forbidden Updated: 2026-10-17 ## When to use it Use [`403 Forbidden`](/status-codes/403) with a Tenant Suspended error when the caller's own credentials and account are fine, but the tenant the request targets, such as an organization, workspace or team, has been suspended. Typical causes are an unpaid subscription on the organization, a terms-of-service violation by the tenant, or a contract that has ended while its data is retained for a grace period. The distinction from `account-frozen` is scope. In a [multi-tenant](/guides/multi-tenancy) product, one user often belongs to several tenants. Freezing the user's account blocks every request that user makes; suspending a tenant blocks every request into that tenant, from every user, while the same user can keep working in their other tenants. The client needs to know which it hit: a frozen account is the user's problem to resolve, a suspended tenant is for the tenant's owner or billing contact. Say who can lift the suspension. The developer seeing this error is usually not the person who can fix it, so point them at the tenant's admin or billing contact rather than at a generic support page. ## When not to use it Do not use it when the suspension applies to the caller's own account across all tenants. That is `account-frozen`. Do not use it when the caller is not a member of the tenant at all. They should not learn whether that tenant exists or what state it is in, so return `resource-not-found` (404), as you would for any other tenant's resources. Only members, or callers already entitled to see the tenant, should receive this type. Do not use it when the tenant is active and only one feature is unavailable on its plan. That is `feature-disabled`. Do not use it when the tenant has been deleted, not suspended. If the data is gone for good and you keep a tombstone, that is `gone` (410). ## Example response ```json { "type": "https://apiguide.dev/errors/tenant-suspended", "title": "Tenant Suspended", "status": 403, "detail": "The organization 'acme' is suspended because its subscription is past due. An organization owner can restore access by updating the payment method.", "instance": "/v1/orgs/acme/projects", "tenant": "acme", "reason": "billing_past_due", "suspendedAt": "2026-10-10T00:00:00Z" } ``` Decide whether reads stay open during a suspension. Letting members read and export their data while blocking writes is often the kinder policy, and your contracts may require it. If you do that, return this type only for the operations that are blocked. --- # Token Revoked > Use `401 Unauthorized` with a Token Revoked error when the client presents an access token or API key that was valid, has not expired, and has since been revoked: the user signed out, an admin disabled the integration, the key was rotated after a leak, or the authorization server revoked the grant it belonged to. Source: https://apiguide.dev/errors/token-revoked Problem type URI: https://apiguide.dev/errors/token-revoked Status: 401 Unauthorized Updated: 2026-10-17 ## When to use it Use [`401 Unauthorized`](/status-codes/401) with a Token Revoked error when the client presents an access token or API key that was valid, has not expired, and has since been revoked: the user signed out, an admin disabled the integration, the key was rotated after a leak, or the authorization server revoked the grant it belonged to. The distinction from expiry is what the client should do next. An expired access token is routine, and the client refreshes it silently. A revoked one usually means the delegation behind it is gone. RFC 7009 says revoking a refresh token SHOULD also invalidate the access tokens issued under the same grant, so a client that tries to refresh will often fail as well. Telling it the token was revoked lets it skip the doomed refresh and send the user back through sign-in, or alert an operator that a key was rotated. RFC 6750's `invalid_token` error code covers this case explicitly, defined as an access token that is "expired, revoked, malformed, or invalid for other reasons". Send it in the [`WWW-Authenticate`](/headers/www-authenticate) challenge that RFC 9110 requires on every 401, and use the problem type to say which of those it was. The [token lifecycle guide](/guides/token-lifecycle) covers revocation and why it is harder for JWTs. ## When not to use it Do not use it unless you actually know the token was revoked. A resource server that validates JWTs locally cannot tell a revoked token from a valid one without a denylist, and an introspection response under RFC 7662 reports `"active": false` for revoked, expired and unknown tokens alike. If all you know is that the token is not valid, use `unauthorized`. Do not use it for an expired token. That is `expired-authentication-token`, and the client should refresh rather than re-authenticate. Do not use it when the token is valid and the account is suspended. The token was not revoked; the account is blocked, which is `account-frozen` (403). Do not use it if confirming that a token once existed would leak something. For a leaked API key being probed by a third party, a generic `unauthorized` gives the prober less. Reserve this type for cases where the caller is plausibly the token's legitimate holder, such as a session token sent from the client it was issued to. ## Example response ```http HTTP/1.1 401 Unauthorized Content-Type: application/problem+json WWW-Authenticate: Bearer error="invalid_token", error_description="The access token has been revoked" { "type": "https://apiguide.dev/errors/token-revoked", "title": "Token Revoked", "status": 401, "detail": "This access token was revoked on 2026-10-16T18:04:00Z. Sign in again to obtain a new token.", "instance": "/v1/projects" } ``` Leave out who revoked the token and why. The legitimate user can find that in your dashboard or audit log, and anyone else holding the token should learn nothing beyond the fact that it no longer works. --- # Too Early > Use `425 Too Early` when a request arrived in TLS 1.3 early data (0-RTT), or was forwarded by an intermediary with `Early-Data: 1`, and processing a replayed copy of it would cause a side effect you are not prepared to repeat. Source: https://apiguide.dev/errors/too-early Problem type URI: https://apiguide.dev/errors/too-early Status: 425 Too Early Updated: 2026-10-17 ## When to use it Use [`425 Too Early`](/status-codes/425) when a request arrived in TLS 1.3 early data (0-RTT), or was forwarded by an intermediary with [`Early-Data: 1`](/headers/early-data), and processing a replayed copy of it would cause a side effect you are not prepared to repeat. RFC 8470 defines the code as a server that "is unwilling to risk processing a request that might be replayed". The request itself is fine. Only the way it was delivered is the problem: early data is sent before the handshake completes, so an attacker who captured it can send it again. RFC 8470 says a user agent SHOULD retry a 425 automatically, and that the retry MUST NOT be sent in early data. Most clients never see this response, because their HTTP stack retries it for them. The realistic cases in an API are requests the client treated as safe that are not safe on your server: a [`GET`](/methods/get) that consumes a single-use link, accepts an invitation, or counts against a metered quota. Decide per route whether early data is acceptable, and answer 425 on the routes where it is not. ## When not to use it Do not use it unless the request actually arrived in early data or carries `Early-Data: 1`. RFC 8470 says a server SHOULD NOT send 425 otherwise, because only then can it assume the client understands the code and is able to retry. Do not use it as a general replay or duplicate check. A request repeated after the handshake, or a duplicate [`POST`](/methods/post), is a retry problem, not an early-data problem. That is what an [`Idempotency-Key`](/headers/idempotency-key) is for, and a misused key is `idempotency-key-conflict`. Do not use it to shed load or to ask the client to back off. A 425 retry can go out as soon as the handshake completes. If the server cannot take the request right now, that is `service-unavailable` (503). ## Example response ```http HTTP/1.1 425 Too Early Content-Type: application/problem+json { "type": "https://apiguide.dev/errors/too-early", "title": "Too Early", "status": 425, "detail": "This request was received in TLS early data, and accepting an invitation cannot be safely replayed. Retry it after the TLS handshake completes.", "instance": "/v1/invitations/3f9c2a/accept" } ``` RFC 8470 requires an intermediary to forward a 425 back to the client when the request it forwarded carried `Early-Data: 1`, so the origin's answer reaches the party that can actually retry. The code is not cacheable by default. --- # Unauthorized > Use 401 Unauthorized when the request lacks valid authentication credentials. Source: https://apiguide.dev/errors/unauthorized Problem type URI: https://apiguide.dev/errors/unauthorized Status: 401 Unauthorized Updated: 2026-10-13 ## When to use it Use 401 Unauthorized when the request lacks valid authentication credentials. This applies when the client sends no authorization headers/cookies, or when the credentials provided are completely invalid, malformed, or unrecognized by the system. A 401 response requires that the server must include a `WWW-Authenticate` header specifying the authentication scheme (e.g. `WWW-Authenticate: Bearer realm="api"`). ## When not to use it Do not use 401 if the client has successfully authenticated, but lacks the necessary permissions or scope to access the resource (use `insufficient-scope` / 403 instead). Do not use this if the token is known but expired (use the more specific `expired-authentication-token` error). ## Example response ```json { "type": "https://apiguide.dev/errors/unauthorized", "title": "Unauthorized", "status": 401, "detail": "The API key provided is invalid or has been revoked.", "instance": "/v1/leads" } ``` Include a header to specify the authentication scheme: ```http WWW-Authenticate: Bearer realm="api" ``` --- # Unavailable For Legal Reasons > Use `451 Unavailable For Legal Reasons` when you are denying access to a resource because of a legal demand: a court order, a takedown notice, a sanctions rule, or a regulator's instruction that this data may not be served to this caller or in this jurisdiction. Source: https://apiguide.dev/errors/unavailable-for-legal-reasons Problem type URI: https://apiguide.dev/errors/unavailable-for-legal-reasons Status: 451 Unavailable For Legal Reasons Updated: 2026-10-17 ## When to use it Use [`451 Unavailable For Legal Reasons`](/status-codes/451) when you are denying access to a resource because of a legal demand: a court order, a takedown notice, a sanctions rule, or a regulator's instruction that this data may not be served to this caller or in this jurisdiction. RFC 7725 defines the code as a server "denying access to the resource as a consequence of a legal demand". RFC 7725 says the response SHOULD explain the demand in the body: the party making it, the legislation or regulation it rests on, and which classes of person and resource it applies to. In a problem response that explanation goes in `detail`, with the structured parts as extension members so a client can show them without parsing prose. The RFC also says the blocking entity SHOULD send a [`Link`](/headers/link) header with `rel="blocked-by"` identifying itself. That is you, or whoever operates the server that refused the request, not the court or government that ordered the block. ## When not to use it Do not use it for restrictions that are your own policy rather than a legal demand. A feature you have not launched in a country, a licensing deal that does not cover a region, or a terms-of-service decision is `forbidden` (403). 451 makes a specific claim about why access is denied, and claiming a legal demand you never received misleads the people trying to understand the block. Do not use it when you are not permitted to disclose that a demand exists. Some orders forbid that, and RFC 7725 acknowledges that clients cannot rely on receiving 451 for this reason. Use `resource-not-found` or `forbidden` instead, as your counsel directs. Do not use it for content you have removed permanently for everyone. That is `gone` (410). 451 says the resource is withheld from this request, and RFC 7725 notes that it implies neither that the resource exists nor that it does not. RFC 7725 makes a 451 response cacheable by default. If the block applies per jurisdiction or per caller, send `Cache-Control: private` or a short lifetime, so a shared cache does not serve one region's block to everyone. ## Example response ```http HTTP/1.1 451 Unavailable For Legal Reasons Content-Type: application/problem+json Link: ; rel="blocked-by" Cache-Control: private, max-age=3600 { "type": "https://apiguide.dev/errors/unavailable-for-legal-reasons", "title": "Unavailable For Legal Reasons", "status": 451, "detail": "This listing cannot be served to requests from Germany because of a court order. See the transparency page for the order and its scope.", "instance": "/v1/listings/88231", "jurisdiction": "DE", "demandedBy": "Example District Court", "blockedBy": "https://example.com/legal/transparency" } ``` Keep the block scoped to what the demand actually covers. If an order applies to one listing in one country, the rest of the catalog, and the same listing everywhere else, should keep working. --- # Unprocessable Query > Use 422 when the request is syntactically valid but semantically wrong. Source: https://apiguide.dev/errors/unprocessable-query Problem type URI: https://apiguide.dev/errors/unprocessable-query Status: 422 Unprocessable Content Updated: 2026-10-14 ## When to use it Use 422 when the request is syntactically valid but semantically wrong. The client sent well formed JSON or query parameters, the shape matches what you expect, but the values don't make sense together. A pagination request asking for `page=2` on a collection with one page of results is a 422. The request is valid on its face. The server understood it fine. It just can't be fulfilled because the state of the data doesn't support it. ## When not to use it 400 is for requests the server cannot parse. Malformed JSON in the body is `malformed-request-body`. A query parameter the endpoint never accepts, such as an unsupported `sort` field, is `invalid-query-parameter`. Do not use this type for a request body that parses but fails validation, such as a missing required field, a string where an integer belongs, or an invalid email address. RFC 9110 defines 422 for content whose type and syntax the server understands but whose instructions it cannot process, so those are 422 too, but they belong to `validation-failed`, which carries per-field errors. Use this type when the problem is the query: values that are individually valid but cannot be satisfied together or against the current data. ## Example response ```json { "type": "https://apiguide.dev/errors/unprocessable-query", "title": "Unprocessable Query", "status": 422, "detail": "Requested page 2 exceeds the available range of 1 page.", "instance": "/v1/leads?page=2" } ``` --- # Unsupported API Version > Use 400 with an Unsupported API Version error when the client selects an API version through a request header or query parameter, and the server does not serve that version. Source: https://apiguide.dev/errors/unsupported-api-version Problem type URI: https://apiguide.dev/errors/unsupported-api-version Status: 400 Bad Request Updated: 2026-10-14 ## When to use it Use 400 with an Unsupported API Version error when the client selects an API version through a request header or query parameter, and the server does not serve that version. This covers date-based version headers such as Stripe's `Stripe-Version`, custom headers such as `Api-Version: 2019-04-01`, and query parameters such as `?api-version=2019-04-01`. The version may be unknown (a typo, a date that was never released) or retired. The status code depends on where the version lives, because that decides which part of the request is wrong. This type is for the header and query parameter case, and 400 is the right code there: | Version carried in | Example | Status | Error type | | :--- | :--- | :--- | :--- | | Header or query parameter | `Api-Version: 2019-04-01` | 400 | `unsupported-api-version` | | Path, never existed | `/v9/orders` | 404 | `resource-not-found` | | Path, retired | `/v1/orders` after sunset | 410 | `gone` | | Media type in `Accept` | `application/vnd.example.v9+json` | 406 | `not-acceptable` | 400 is right for header versions because the target resource still exists and is still available. Only the version selector the client sent is unacceptable, which is a defect in the request. GitHub takes a different view and returns 410 Gone for a retired `X-GitHub-Api-Version`. 410 says the target resource is no longer available, and here it still is, under every supported version, so use 400 and reserve 410 for a URI that has actually gone. Always list the supported versions in the response. The client's next step is to pick one, and it should not have to read your docs to find out what they are. ## When not to use it Do not use it for a path-versioned URI. `/v9/orders` is a URI that does not identify a resource, so it is `resource-not-found` (404), and a retired `/v1/orders` is `gone` (410), where the body can name the successor. Do not use it for a version requested through a media type parameter or vendor media type in [`Accept`](/headers/accept). That is content negotiation failing, so it is `not-acceptable` (406). Do not use it when the client sent no version at all and your API requires one. That is a missing required input; describe it in the same 400 if you like, but do not report a missing version as an unsupported one. If your API falls back to a default version when none is sent, say which version you used in a response header so the client can pin it. Do not use it for an ordinary unsupported query parameter that has nothing to do with versioning. That is `invalid-query-parameter`. ## Example response ```json { "type": "https://apiguide.dev/errors/unsupported-api-version", "title": "Unsupported API Version", "status": 400, "detail": "API version 2019-04-01 is not supported. Supported versions are 2025-01-15, 2025-09-01 and 2026-06-01.", "instance": "/v1/orders", "requestedVersion": "2019-04-01", "supportedVersions": ["2025-01-15", "2025-09-01", "2026-06-01"] } ``` The request that triggers it names a version the server no longer serves: ```http GET /v1/orders HTTP/1.1 Host: api.example.com Api-Version: 2019-04-01 Accept: application/json ``` Do not silently fall back to another version when the client asked for one you do not have. A client that pinned a version expects that version's response shapes; serving a different version breaks it in ways that surface far from the cause. --- # Unsupported Media Type > Use 415 Unsupported Media Type when the server rejects a request because the request's payload format is not supported. Source: https://apiguide.dev/errors/unsupported-media-type Problem type URI: https://apiguide.dev/errors/unsupported-media-type Status: 415 Unsupported Media Type Updated: 2026-07-09 ## When to use it Use 415 Unsupported Media Type when the server rejects a request because the request's payload format is not supported. This is typically driven by the `Content-Type` header of the request (for example, a client sending XML `application/xml` or form data `application/x-www-form-urlencoded` to an API endpoint that only accepts JSON `application/json`). It can also apply to binary uploads, such as uploading a `.gif` file to a profile picture endpoint that only accepts `.jpg` or `.png`. ## When not to use it Do not use 415 if the `Content-Type` header is correct, but the contents inside the payload fail to parse. For example, if the content is marked as `application/json` but has a syntax error, use `malformed-request-body` (400). ## Example response ```json { "type": "https://apiguide.dev/errors/unsupported-media-type", "title": "Unsupported Media Type", "status": 415, "detail": "The Content-Type 'application/xml' is not supported. Supported content types: application/json.", "instance": "/v1/leads" } ``` --- # URI Too Long > Use 414 URI Too Long when the target URI is longer than the server is willing to interpret. Source: https://apiguide.dev/errors/uri-too-long Problem type URI: https://apiguide.dev/errors/uri-too-long Status: 414 URI Too Long Updated: 2026-10-14 ## When to use it Use 414 URI Too Long when the target URI is longer than the server is willing to interpret. RFC 9110 defines it that way, and RFC 9112 makes it mandatory for HTTP/1.1: a server that receives a request-target "longer than any URI it wishes to parse MUST respond with a 414". RFC 9110 calls it a "rare condition" and names three causes: a client that converted a `POST` into a `GET` with long query information, a client caught in a redirect loop that keeps growing the URI, and an attack probing for security holes. In APIs the first is by far the most common: a `GET` that filters by a long list of IDs, or a search encoded entirely in the query string, which grows with the user's input until it hits a limit. There is no fixed maximum. RFC 9110 recommends that senders and recipients support URIs of at least 8000 octets, and RFC 9112 recommends request lines of at least 8000 octets. Every hop between client and application has its own limit, and the smallest one wins. nginx, for example, rejects a request line longer than one `large_client_header_buffers` buffer, 8K by default, with 414. Find the lowest limit on your path and document it. ## When not to use it Do not use it when the header section is too large, for example because of oversized cookies or a large bearer token. That is `request-header-fields-too-large` (431). Do not use it when the request body is too large; that is `payload-too-large` (413). Do not use it when the URI fits within your limits but asks for more than your business rules allow, such as 500 IDs on a filter capped at 100. The server read the URI fine, so that is `invalid-query-parameter` (400), naming the parameter and the cap. ## Example response ```json { "type": "https://apiguide.dev/errors/uri-too-long", "title": "URI Too Long", "status": 414, "detail": "The request URI is 11204 bytes long. This API accepts URIs up to 8000 bytes. Send large queries as a QUERY or POST request with the query in the body.", "instance": "/v1/leads", "maxLength": 8000 } ``` The fix belongs in the API design as well as the client. If a query can legitimately grow beyond a few kilobytes, give it a body: [`QUERY`](/methods/query), standardized in RFC 10008, is safe and idempotent and carries the query in the content, and a `POST` to a search resource works where `QUERY` is not yet supported. Do not tell clients to split one logical query across several `GET` requests and merge the results themselves. The limit usually trips at a proxy or load balancer before the request reaches your application, so the body above comes from whatever generates that edge's error pages. Configure it to return `application/problem+json`. RFC 9110 also makes 414 heuristically cacheable, so a cache may reuse it without explicit freshness information. --- # Validation Failed > Use 422 Validation Failed when the request payload is syntactically correct and readable (like valid JSON), but fails to meet the server's business constraints or data validation rules. Source: https://apiguide.dev/errors/validation-failed Problem type URI: https://apiguide.dev/errors/validation-failed Status: 422 Unprocessable Content Updated: 2026-10-14 ## When to use it Use 422 Validation Failed when the request payload is syntactically correct and readable (like valid JSON), but fails to meet the server's business constraints or data validation rules. Typical examples include a required field being missing, a string failing to meet a min/max length, or a field violating dependency rules (e.g. `start_date` must be before `end_date`). Type and format errors in a body that parses (a malformed email string, a boolean where a number belongs) are validation failures too, and get 422. The line with 400 is parsing: if the server cannot read the payload at all, it is `malformed-request-body`. Semantic problems with a query, rather than a body, are `unprocessable-query`. ## When not to use it Do not use 422 for syntactically invalid payloads (use `malformed-request-body` / 400 instead). Do not use this code for authorization checks (use 401 or 403) or resource existence failures (use 404). ## Example response ```json { "type": "https://apiguide.dev/errors/validation-failed", "title": "Validation Failed", "status": 422, "detail": "The end_date must be a date after start_date.", "errors": { "end_date": [ "The end_date must be a date after start_date." ] }, "instance": "/v1/leads" } ``` --- # 100 Continue > The server has received the request headers and the client should proceed to send the request body. Source: https://apiguide.dev/status-codes/100 Class: informational Defined in: RFC 9110, Section 15.2.1 Updated: 2026-07-09 ## What does HTTP status code 100 mean? The 100 Continue status code is an informational response indicating that the initial part of the request has been received and has not yet been rejected by the server. The client should continue with the request or ignore this response if the request has already been finished. ## When to use it in APIs Typically used in large file uploads (like media or bulk datasets) using the `Expect: 100-continue` header. The client sends headers first to check if the server will accept the request (based on authorization, content size, etc.) before uploading the heavy body payload. ## How it compares to other codes * **103 Early Hints**: Used to send headers (like preloading assets) before the final response, whereas 100 is strictly a gatekeeper for body uploads. --- # 101 Switching Protocols > The server understands the Upgrade header field sent by the client and is switching protocols. Source: https://apiguide.dev/status-codes/101 Class: informational Defined in: RFC 9110, Section 15.2.2 Updated: 2026-10-14 ## What does HTTP status code 101 mean? The 101 Switching Protocols status code indicates that the server is agreeing to switch protocols as requested by the client via the [`Upgrade`](/headers/upgrade) header. ## When to use it in APIs This is the standard response returned during a WebSocket handshake. A client makes an HTTP request with `Upgrade: websocket` and the server responds with 101 to transition the TCP connection into a bi-directional WebSocket stream. ## How it compares to other codes * **100 Continue**: Handles body transfer coordination, whereas 101 handles connection protocol upgrades. --- # 102 Processing > The server has received and is processing the request, but no response is available yet. Source: https://apiguide.dev/status-codes/102 Class: informational Defined in: RFC 2518 Updated: 2026-07-09 ## What does HTTP status code 102 mean? The 102 Processing status code is an interim response used to inform the client that the server has accepted the complete request but has not yet finished processing it. It exists so the client does not time out while the server works on a long-running operation. ## When to use it in APIs Defined by WebDAV (RFC 2518, carried forward in RFC 4918) for methods like `PROPFIND` or `COPY` that may operate on many resources and take a long time to complete. A server can send a 102 to reset the client's timeout clock while it continues processing. ## How it compares to other codes * **100 Continue**: Sent before the client uploads a request body, whereas 102 is sent after the request is fully received, while the server is still working on it. --- # 103 Early Hints > Allows the server to send link headers to prefetch resources while compiling the main response. Source: https://apiguide.dev/status-codes/103 Class: informational Defined in: RFC 8297 Updated: 2026-07-09 ## What does HTTP status code 103 mean? The 103 Early Hints status code is primarily intended to be used with the Link header to allow the user agent to start preloading resources while the server prepares the final response payload. ## When to use it in APIs Useful in high-performance web applications or APIs returning HTML/critical assets where the browser can benefit from preloading CSS, JS, or font assets early in the connection lifecycle. ## How it compares to other codes * **200 OK**: The final successful response. 103 is a pre-response hint sent before 200. --- # 200 OK > The request has succeeded. The response payload contains the requested resource representation. Source: https://apiguide.dev/status-codes/200 Class: success Defined in: RFC 9110, Section 15.3.1 Updated: 2026-07-09 ## What does HTTP status code 200 mean? The 200 OK status code is the generic success response indicating that the request was processed successfully and the result is returned in the response body. ## When to use it in APIs Use 200 for successful `GET` requests returning data, successful `PUT` or `PATCH` updates that return the modified resource, and successful `POST` operations that do not result in resource creation. ## How it compares to other codes * **201 Created**: Use 201 when a new resource was created, reserving 200 for read, update, or non-creational actions. * **204 No Content**: Use 204 when a delete or update succeeded but returns no response payload. --- # 201 Created > The request has been fulfilled and has resulted in a new resource being created. Source: https://apiguide.dev/status-codes/201 Class: success Defined in: RFC 9110, Section 15.3.2 Updated: 2026-07-09 ## What does HTTP status code 201 mean? The 201 Created status code indicates that the request was successful and resulted in the creation of one or more new resources on the server. ## When to use it in APIs Use 201 for successful `POST` requests that create new records (e.g. creating a lead, user, or charge). Ideally, include a `Location` header containing the URI of the newly created resource. ## How it compares to other codes * **200 OK**: Reserves for successful reads or updates that do not create new records. * **202 Accepted**: Use 202 if the resource creation is queued or processed asynchronously rather than completed. --- # 202 Accepted > The request has been accepted for processing, but the processing has not been completed. Source: https://apiguide.dev/status-codes/202 Class: success Defined in: RFC 9110, Section 15.3.3 Updated: 2026-07-09 ## What does HTTP status code 202 mean? The 202 Accepted status code indicates that the request has been received and validated, but the actual execution is being handled asynchronously (e.g., in a background queue). ## When to use it in APIs Use 202 for long-running processes (like generating a heavy PDF report, batch updates, or provisioning servers) to avoid holding the HTTP connection open. Often returns a link in the response body or a `Location` header to poll for the job status. ## How it compares to other codes * **201 Created**: Reserves for synchronous, immediate resource creation. * **200 OK**: Reserves for synchronous request completion. --- # 203 Non-Authoritative Information > The server is a transforming proxy that received a 200 OK from its origin but is returning a modified payload. Source: https://apiguide.dev/status-codes/203 Class: success Defined in: RFC 9110, Section 15.3.4 Updated: 2026-07-09 ## What does HTTP status code 203 mean? The 203 Non-Authoritative Information status code indicates that the request was successful, but the payload has been modified by a transforming proxy between the origin server and the client. ## When to use it in APIs Rarely used in REST APIs. It occasionally surfaces when an API proxy or CDN intercepts a response and rewrites headers or payload fields before forwarding it to the client. ## How it compares to other codes * **200 OK**: Represents unmodified, authoritative content direct from the origin server. --- # 204 No Content > The request was successful, but the response body is intentionally empty. Source: https://apiguide.dev/status-codes/204 Class: success Defined in: RFC 9110, Section 15.3.5 Updated: 2026-07-09 ## What does HTTP status code 204 mean? The 204 No Content status code indicates that the server successfully processed the request, but there is no payload to return in the response body. ## When to use it in APIs Standard response for successful `DELETE` operations. Can also be used for `POST` or `PUT` requests (e.g., checking in, triggering a simple webhook, or saving settings) where returning the resource representation is unnecessary. ## How it compares to other codes * **200 OK**: Used when the response contains a representation of the resource. * **205 Reset Content**: Similar to 204 but instructs the client's user interface to reset the form or view. --- # 205 Reset Content > The server fulfilled the request and desires that the user agent reset the document view. Source: https://apiguide.dev/status-codes/205 Class: success Defined in: RFC 9110, Section 15.3.6 Updated: 2026-07-09 ## What does HTTP status code 205 mean? The 205 Reset Content status code indicates that the server successfully completed the request and requests that the client reset the interface view that sent the request (e.g., clearing a form). ## When to use it in APIs Rarely used in pure JSON APIs, but sometimes returned by endpoints handling form submissions to tell frontend applications to clear inputs. ## How it compares to other codes * **204 No Content**: Responds with no body, but does not ask the client to reset any UI states. --- # 206 Partial Content > The server is delivering only part of the resource due to a Range header sent by the client. Source: https://apiguide.dev/status-codes/206 Class: success Defined in: RFC 9110, Section 15.3.7 Updated: 2026-07-09 ## What does HTTP status code 206 mean? The 206 Partial Content status code is returned when the client requested a specific byte range of a resource (using the `Range` header) and the server is delivering only that portion. ## When to use it in APIs Useful for APIs serving binary files, videos, or large log files, enabling clients to download files in chunks or resume interrupted downloads. ## How it compares to other codes * **200 OK**: Returns the entire resource, not a segmented portion. --- # 207 Multi-Status > The response body contains multiple independent status codes for a batch of sub-operations. Source: https://apiguide.dev/status-codes/207 Class: success Defined in: RFC 4918 Updated: 2026-07-09 ## What does HTTP status code 207 mean? The 207 Multi-Status status code indicates that the response body is a single XML (or JSON, in modern APIs) document containing several separate status codes, one for each of multiple independent operations performed as part of the same request. ## When to use it in APIs Defined by WebDAV (RFC 4918) for operations like `PROPFIND` or batch `COPY`/`DELETE` requests that act on multiple resources at once, where some may succeed and others may fail. It is also a useful pattern for bulk or batch API endpoints that need to report per-item success and failure in a single call. ## How it compares to other codes * **200 OK**: Implies the entire request succeeded as a single unit, whereas 207 reports mixed outcomes across several sub-requests. * **208 Already Reported**: Used inside a 207 response to avoid repeating bindings that were already listed for a previously enumerated resource. --- # 208 Already Reported > Used inside a 207 Multi-Status response to avoid repeatedly enumerating the same bound resource. Source: https://apiguide.dev/status-codes/208 Class: success Defined in: RFC 5842 Updated: 2026-07-09 ## What does HTTP status code 208 mean? The 208 Already Reported status code is used inside a 207 Multi-Status response to indicate that the members of a DAV binding have already been enumerated in a preceding part of the same response, and are not being included again to avoid infinite repetition. ## When to use it in APIs Defined by RFC 5842 for WebDAV Binding Extensions, where a single resource can be reached through multiple bindings (similar to hard links). When enumerating a collection that contains repeated bindings, a server sends 208 for a resource it has already reported rather than duplicating its full status entry. ## How it compares to other codes * **207 Multi-Status**: The parent response wrapper that carries multiple statuses, one of which may be 208 for an already-listed resource. --- # 226 IM Used > The server has fulfilled a request for the resource and the response represents the result of applying one or more instance manipulations. Source: https://apiguide.dev/status-codes/226 Class: success Defined in: RFC 3229 Updated: 2026-07-09 ## What does HTTP status code 226 mean? The 226 IM Used status code indicates that the server has fulfilled a `GET` request and the response is a representation of the result of one or more instance manipulations applied to the current instance, as negotiated using the `A-IM` request header. ## When to use it in APIs Defined by RFC 3229 for delta encoding, where a client that already holds an older version of a resource asks the server to return only the difference (the "delta") rather than the full body. The server responds with 226 and an `IM` header identifying the instance manipulation (e.g., a diff algorithm) used to produce the payload, letting the client reconstruct the current version while saving bandwidth. ## How it compares to other codes * **200 OK**: Returns the full current representation, whereas 226 returns only a delta relative to a version the client already has. * **206 Partial Content**: Returns a byte range of a resource requested via the `Range` header, while 226 returns a computed difference negotiated via the `A-IM` header. --- # 300 Multiple Choices > The request has more than one possible response and the user agent or user should choose one. Source: https://apiguide.dev/status-codes/300 Class: redirection Defined in: RFC 9110, Section 15.4.1 Updated: 2026-09-24 ## What does HTTP status code 300 mean? The 300 Multiple Choices status code indicates that the requested resource has multiple representations, each with its own location. ## When to use it in APIs Can be used in content negotiation where a resource is available in multiple formats (e.g. JSON, XML, CSV) and the client did not specify an Accept header. In practice this is rare, and almost no real-world APIs implement server-driven negotiation this way, preferring a single default representation or a 406 when the Accept header can't be satisfied. ## How it compares to other codes * **301 Moved Permanently**: Directs to one single location, whereas 300 offers options. --- # 301 Moved Permanently > The requested resource has been assigned a new permanent URI and future references should use it. Source: https://apiguide.dev/status-codes/301 Class: redirection Defined in: RFC 9110, Section 15.4.2 Updated: 2026-07-09 ## What does HTTP status code 301 mean? The 301 Moved Permanently status code indicates that the target resource has been permanently moved to a new URI specified in the `Location` header. ## When to use it in APIs Use when restructuring API paths (e.g., moving `/v1/leads` to `/v2/leads` permanently). However, be aware that many HTTP clients will change post requests to GET requests when following a 301. ## How it compares to other codes * **308 Permanent Redirect**: The modern replacement that guarantees the HTTP method (e.g. POST) remains unchanged during redirect. * **302 Found**: A temporary redirect. --- # 302 Found > The requested resource resides temporarily under a different URI. Source: https://apiguide.dev/status-codes/302 Class: redirection Defined in: RFC 9110, Section 15.4.3 Updated: 2026-07-09 ## What does HTTP status code 302 mean? The 302 Found status code indicates that the resource is temporarily located at a different URI specified in the `Location` header. ## When to use it in APIs Used for temporary redirections. Like 301, standard clients often change POST to GET when redirected via 302. ## How it compares to other codes * **307 Temporary Redirect**: The modern counterpart that guarantees the HTTP method does not change during redirection. * **301 Moved Permanently**: Represents a permanent redirect. --- # 303 See Other > Directs the client to get the requested resource at another URI using a GET request. Source: https://apiguide.dev/status-codes/303 Class: redirection Defined in: RFC 9110, Section 15.4.4 Updated: 2026-07-09 ## What does HTTP status code 303 mean? The 303 See Other status code tells the client that the resource has been created or processed, and the result can be fetched via a `GET` request at a different URI. ## When to use it in APIs Excellent for POST-redirect-GET patterns. After a client submits a form or resource creation request, return a 303 redirecting them to the newly created resource detail page. ## How it compares to other codes * **302 Found**: Used for generic redirects, whereas 303 explicitly forces the client to use a GET request on the target URI. --- # 304 Not Modified > Instructs the client that the cached version of the resource is still valid. Source: https://apiguide.dev/status-codes/304 Class: redirection Defined in: RFC 9110, Section 15.4.5 Updated: 2026-07-09 ## What does HTTP status code 304 mean? The 304 Not Modified status code indicates that the resource has not changed since the last request, so the server is not sending a response body. The client can safely use its cached copy. ## When to use it in APIs Used for HTTP caching. The client sends conditional headers like `If-None-Match` (containing an ETag) or `If-Modified-Since`. If the server detects no changes, it returns a 304. ## How it compares to other codes * **200 OK**: Returns the full payload, whereas 304 returns no body to conserve bandwidth. --- # 305 Use Proxy > Deprecated. Indicated that the requested resource had to be accessed through the proxy given in the response. Source: https://apiguide.dev/status-codes/305 Class: redirection Defined in: RFC 9110, Section 15.4.6 Updated: 2026-07-09 ## What does HTTP status code 305 mean? The 305 Use Proxy status code was originally defined to tell a client that the requested resource must be accessed through the proxy specified in the `Location` header. It never saw meaningful adoption. ## When to use it in APIs Do not use it. RFC 7231 explicitly deprecates 305 due to security concerns: it could be used to redirect a client's traffic through an arbitrary proxy, and most browsers and HTTP clients ignore it entirely for this reason. It is documented here only for completeness and historical reference, not as a viable option for API design. ## How it compares to other codes * **300 Multiple Choices**: A live, general-purpose redirection code, unlike 305, which is deprecated and unsupported in practice. --- # 306 Unused > Reserved. Formerly defined as "Switch Proxy" in an early draft, this code was never used and is no longer part of the standard beyond being reserved. Source: https://apiguide.dev/status-codes/306 Class: redirection Defined in: RFC 9110, Section 15.4.7 Updated: 2026-10-14 ## What does HTTP status code 306 mean? HTTP status code 306 is a reserved code that carries no active meaning. It was defined in an early draft of the HTTP/1.1 specification as "Switch Proxy", intended to tell a client to use a specified proxy for subsequent requests. That behavior was never adopted, the code was dropped from the standard, and 306 is now simply reserved so that it will not be reassigned. ## When to use it in APIs Never. There is no valid scenario for returning 306 from an API. Because the code is reserved and has no defined semantics, clients will not interpret it usefully. If you need to direct a client to a proxy, that is handled by proxy configuration and the 407 Proxy Authentication Required flow, not by a redirection status. For genuine redirects, choose an active 3xx code such as 307 or 308. ## How it compares to other codes * **300 Multiple Choices**: An active redirection code indicating the resource has several representations for the client to choose from, unlike the dormant 306. * **305 Use Proxy**: The neighboring code that actually addressed proxy use, though it too is now deprecated for security reasons. --- # 307 Temporary Redirect > The resource resides temporarily under a different URI. Method must not be changed. Source: https://apiguide.dev/status-codes/307 Class: redirection Defined in: RFC 9110, Section 15.4.8 Updated: 2026-07-09 ## What does HTTP status code 307 mean? The 307 Temporary Redirect status code indicates that the resource is temporarily located at a different URI and the client must reuse the original HTTP method (e.g. POST) when making the redirected request. ## When to use it in APIs Use when redirecting write operations (POST, PUT, DELETE) temporarily, ensuring the client resubmits the actual payload. ## How it compares to other codes * **302 Found**: Allows clients to change the method from POST to GET, whereas 307 strictly forbids it. --- # 308 Permanent Redirect > The resource has been permanently moved. Method must not be changed. Source: https://apiguide.dev/status-codes/308 Class: redirection Defined in: RFC 9110, Section 15.4.9 Updated: 2026-07-09 ## What does HTTP status code 308 mean? The 308 Permanent Redirect status code indicates that the resource has been permanently moved to a new URI and the client must preserve the HTTP method used in the original request. ## When to use it in APIs Use when permanently renaming write endpoints (e.g., changing `/v1/create` to `/v1/register`), preventing clients from dropping their payload. ## How it compares to other codes * **301 Moved Permanently**: Allows method switching (POST to GET), while 308 preserves the original method. --- # 400 Bad Request > The server cannot process the request due to client error (e.g., malformed syntax, invalid framing). Source: https://apiguide.dev/status-codes/400 Class: client-error Defined in: RFC 9110, Section 15.5.1 Updated: 2026-10-14 ## What does HTTP status code 400 mean? The 400 Bad Request status code indicates that the server is unable to understand or process the request due to structural client errors (e.g., parsing errors, malformed headers, or bad syntax). ## When to use it in APIs Use 400 when the request body is syntactically invalid (e.g., malformed JSON) or when dynamic structural constraints fail before domain validation begins (like invalid cursor formats). ## How it compares to other codes * **422 Unprocessable Content**: Use 422 for semantically valid JSON payloads that fail business validation. Use 400 for payloads that cannot even be parsed. --- # 401 Unauthorized > The request lacks valid authentication credentials. The client must authenticate. Source: https://apiguide.dev/status-codes/401 Class: client-error Defined in: RFC 9110, Section 15.5.2 Updated: 2026-07-10 ## What does HTTP status code 401 mean? The 401 Unauthorized status code indicates that the client must authenticate itself to receive the requested response. ## When to use it in APIs Use 401 when the client fails to provide an API key, bearer token, or session credentials, or when the credentials provided are invalid or expired. A 401 response must include a `WWW-Authenticate` header naming the authentication scheme the client should use (e.g. `WWW-Authenticate: Bearer realm="api"`). ## How it compares to other codes * **403 Forbidden**: Use 403 when the client is authenticated but does not possess the permissions/scopes to access the resource. --- # 402 Payment Required > Reserved for future use by RFC 9110. APIs use it when a request is valid but the account cannot pay for it. Source: https://apiguide.dev/status-codes/402 Class: client-error Defined in: RFC 9110, Section 15.5.3 Updated: 2026-10-14 ## What does HTTP status code 402 mean? The 402 Payment Required status code is defined by RFC 9110 only as "reserved for future use". The specification gives it no semantics, so generic clients, proxies and HTTP libraries treat it as an ordinary 4xx. Some APIs, Stripe among them, use it anyway for requests that are valid but fail for payment reasons, such as a declined card. ## When to use it in APIs Use 402 when the request is well-formed and authorized, and a payment would fix it immediately: a declined card, an exhausted prepaid balance, or a subscription that has lapsed for non-payment. Because the status code carries no defined meaning, the response body has to do the work: send a problem type such as [insufficient funds](/errors/insufficient-funds) that tells the client what failed and how to resolve it. Do not use 402 for a plan allowance that resets on its own at the end of a billing period. Waiting fixes that, so it is [`429 Too Many Requests`](/status-codes/429) with `Retry-After`, as described in [quota exceeded](/errors/quota-exceeded). ## How it compares to other codes * **403 Forbidden**: The caller is not permitted to do this, and paying will not change that (for example, a role lacks permission). 402 means the caller is permitted but the account cannot cover the cost. * **429 Too Many Requests**: The caller has used up a rate or period allowance and should retry later. 402 means retrying will not help until a payment is made. --- # 403 Forbidden > The client is authenticated but does not have access rights to the content. Source: https://apiguide.dev/status-codes/403 Class: client-error Defined in: RFC 9110, Section 15.5.4 Updated: 2026-07-09 ## What does HTTP status code 403 mean? The 403 Forbidden status code indicates that the server understands the client's identity, but refuses to authorize access. ## When to use it in APIs Use 403 when an authenticated user attempts to access resources belonging to another tenant, or when a token lacks the required OAuth scopes (e.g., read-only token trying to write). ## How it compares to other codes * **401 Unauthorized**: Means the user's identity is unknown or invalid. 403 means their identity is known, but they lack access. --- # 404 Not Found > The server cannot find the requested resource or URI route. Source: https://apiguide.dev/status-codes/404 Class: client-error Defined in: RFC 9110, Section 15.5.5 Updated: 2026-07-09 ## What does HTTP status code 404 mean? The 404 Not Found status code indicates that the server cannot map the requested URI to a valid route, or the specific resource record requested does not exist. ## When to use it in APIs Use 404 for invalid endpoint URLs or when a model query fails (e.g., GET `/leads/123` where lead 123 does not exist). ## How it compares to other codes * **405 Method Not Allowed**: Use 405 if the URL is valid but the HTTP method (like POST instead of GET) is not supported. --- # 405 Method Not Allowed > The requested URI exists, but the HTTP method used is not supported. Source: https://apiguide.dev/status-codes/405 Class: client-error Defined in: RFC 9110, Section 15.5.6 Updated: 2026-07-09 ## What does HTTP status code 405 mean? The 405 Method Not Allowed status code indicates that the resource exists at the given URI, but the server does not support the HTTP method used in the request. ## When to use it in APIs Returned automatically by route engines when a client attempts to POST to a GET-only endpoint. Must include an `Allow` header listing supported methods. ## How it compares to other codes * **404 Not Found**: Used when the route does not exist at all, whereas 405 indicates the route exists but is restricted to other methods. --- # 406 Not Acceptable > The server cannot produce a response matching the Accept headers sent by the client. Source: https://apiguide.dev/status-codes/406 Class: client-error Defined in: RFC 9110, Section 15.5.7 Updated: 2026-07-09 ## What does HTTP status code 406 mean? The 406 Not Acceptable status code indicates that the server cannot generate a response format that matches the content negotiation criteria specified in the request's `Accept` headers. ## When to use it in APIs Use when a client requests data in XML (`Accept: application/xml`) but your API only supports JSON (`Accept: application/json`). ## How it compares to other codes * **415 Unsupported Media Type**: Deals with the request payload sent *by* the client. 406 deals with the response payload desired *by* the client. --- # 407 Proxy Authentication Required > The client must first authenticate itself with the proxy server. Source: https://apiguide.dev/status-codes/407 Class: client-error Defined in: RFC 9110, Section 15.5.8 Updated: 2026-07-09 ## What does HTTP status code 407 mean? The 407 Proxy Authentication Required status code indicates that the client must authenticate itself through an intermediary proxy server before the request can proceed to the destination. ## When to use it in APIs Rarely used in public API backends; typically thrown by enterprise proxy firewalls. ## How it compares to other codes * **401 Unauthorized**: Identifies authentication needed by the destination origin server, whereas 407 identifies proxy server authentication. --- # 408 Request Timeout > The server timed out waiting for the client to complete the request. Source: https://apiguide.dev/status-codes/408 Class: client-error Defined in: RFC 9110, Section 15.5.9 Updated: 2026-07-09 ## What does HTTP status code 408 mean? The 408 Request Timeout status code indicates that the server did not receive the complete request payload from the client within its configured timeout window. ## When to use it in APIs Use when a client establishes a connection but stalls while sending the request body, or fails to complete the request headers in a timely manner. ## How it compares to other codes * **504 Gateway Timeout**: Represents a timeout *upstream* (server-side), whereas 408 is a timeout on the *client's* connection stream. --- # 409 Conflict > The request conflicts with the current state of the target resource. Source: https://apiguide.dev/status-codes/409 Class: client-error Defined in: RFC 9110, Section 15.5.10 Updated: 2026-10-14 ## What does HTTP status code 409 mean? The 409 Conflict status code indicates that the request cannot be completed because it conflicts with the current state of a resource (e.g. database constraints). ## When to use it in APIs Use 409 for optimistic concurrency conflicts (stale version tags), duplicate unique keys (like email address collisions), or a retry that arrives while the original request with the same `Idempotency-Key` is still in flight. A key reused with a different payload is 422, per the idempotency key draft. ## How it compares to other codes * **422 Unprocessable Content**: Used for general field-level business validation. 409 is reserved for state-driven conflicts. --- # 410 Gone > The resource is permanently deleted and has no redirect address. Source: https://apiguide.dev/status-codes/410 Class: client-error Defined in: RFC 9110, Section 15.5.11 Updated: 2026-07-09 ## What does HTTP status code 410 mean? The 410 Gone status code indicates that the target resource was once available but has been permanently deleted and will not be restored. ## When to use it in APIs Excellent for sunsetted resources, deactivated users, or items deleted in compliance with privacy laws (e.g., GDPR deletion) where you want to explicitly state the deletion is permanent and has no redirect link. ## How it compares to other codes * **404 Not Found**: Represents a generic absence. 410 is an explicit declaration that the resource existed but is gone forever. --- # 411 Length Required > The server refuses to accept the request without a defined Content-Length header. Source: https://apiguide.dev/status-codes/411 Class: client-error Defined in: RFC 9110, Section 15.5.12 Updated: 2026-10-14 ## What does HTTP status code 411 mean? The 411 Length Required status code indicates that the server rejects the request because it requires a `Content-Length` header to safely allocate buffers for the request body. ## When to use it in APIs Typically enforced on file upload or ingestion routes to prevent memory exhaustion attacks. ## How it compares to other codes * **413 Content Too Large**: Fails because the body is too big. 411 fails because the body size was not declared. --- # 412 Precondition Failed > One or more preconditions in the request headers evaluated to false. Source: https://apiguide.dev/status-codes/412 Class: client-error Defined in: RFC 9110, Section 15.5.13 Updated: 2026-07-09 ## What does HTTP status code 412 mean? The 412 Precondition Failed status code indicates that one or more conditional checks specified in the client's request headers (like `If-Match`) failed. ## When to use it in APIs Used in conditional updates. A client submits a PUT request with `If-Match: "etag_value"`. If the resource ETag has changed on the server, the server returns 412 to prevent the client from overwriting concurrent changes. ## How it compares to other codes * **409 Conflict**: A general state conflict. 412 is strictly tied to HTTP headers-based optimistic concurrency control. --- # 413 Content Too Large > The request body size exceeds the maximum limit allowed by the server. Source: https://apiguide.dev/status-codes/413 Class: client-error Defined in: RFC 9110, Section 15.5.14 Updated: 2026-07-14 ## What does HTTP status code 413 mean? The 413 Content Too Large status code indicates that the request body is larger than the server is configured or willing to process. RFC 9110 renamed this code from its former title, "Payload Too Large" (RFC 7231). ## When to use it in APIs Enforced when clients attempt to upload files or batch data arrays exceeding size limits (e.g., uploading a 25MB file to a 10MB route). ## How it compares to other codes * **411 Length Required**: Rejects requests missing the Content-Length header. --- # 414 URI Too Long > The URI requested by the client is longer than the server is willing to interpret. Source: https://apiguide.dev/status-codes/414 Class: client-error Defined in: RFC 9110, Section 15.5.15 Updated: 2026-07-09 ## What does HTTP status code 414 mean? The 414 URI Too Long status code indicates that the URL requested is longer than the server's maximum path limit. ## When to use it in APIs Usually indicates a client error trying to pass extremely large data parameters via URL query parameters in a GET request rather than sending them in a POST body. ## How it compares to other codes * **400 Bad Request**: A general parsing failure, whereas 414 is specific to URL path/query lengths. --- # 415 Unsupported Media Type > The request payload media format is not supported by the server. Source: https://apiguide.dev/status-codes/415 Class: client-error Defined in: RFC 9110, Section 15.5.16 Updated: 2026-07-09 ## What does HTTP status code 415 mean? The 415 Unsupported Media Type status code indicates that the server rejects the request because the payload media format is not supported (e.g., XML payload sent to a JSON-only endpoint). ## When to use it in APIs Use 415 when checking the `Content-Type` header of incoming write requests. If your API requires `application/json` and the client sends `text/xml`, return a 415. ## How it compares to other codes * **406 Not Acceptable**: Refuses response formats based on Accept headers, whereas 415 refuses incoming request body formats. --- # 416 Range Not Satisfiable > The requested byte range cannot be satisfied by the server. Source: https://apiguide.dev/status-codes/416 Class: client-error Defined in: RFC 9110, Section 15.5.17 Updated: 2026-07-09 ## What does HTTP status code 416 mean? The 416 Range Not Satisfiable status code indicates that the client requested a range segment of a file (via the Range header) that falls outside the actual bounds of the resource. ## When to use it in APIs Returned when a client requests bytes 500-1000 of a file that is only 300 bytes long. ## How it compares to other codes * **206 Partial Content**: Returned when the requested range is valid and successfully served. --- # 417 Expectation Failed > The server cannot meet the requirements of the Expect request header. Source: https://apiguide.dev/status-codes/417 Class: client-error Defined in: RFC 9110, Section 15.5.18 Updated: 2026-07-09 ## What does HTTP status code 417 mean? The 417 Expectation Failed status code indicates that the server is unable to satisfy the expectations set in the client's `Expect` request header. ## When to use it in APIs Occasionally returned if a client sends `Expect: 100-continue` but the server cannot comply. ## How it compares to other codes * **100 Continue**: The positive response indicating that the expectation *can* be met. --- # 418 Unused > Reserved. Defined as "I'm a teapot" in the April 1 joke RFC 2324, and reserved by RFC 9110 because the joke was deployed too widely to reassign. Source: https://apiguide.dev/status-codes/418 Class: client-error Defined in: RFC 9110, Section 15.5.19 Updated: 2026-10-14 ## What does HTTP status code 418 mean? HTTP status code 418 is reserved and has no defined meaning in HTTP. It began as "I'm a teapot", part of the Hyper Text Coffee Pot Control Protocol in RFC 2324, an April 1 RFC that lampooned ways HTTP was abused. The joke was deployed often enough that RFC 9110 (Section 15.5.19) marks 418 as "(Unused)" and reserves it in the IANA registry, so it cannot be assigned to another use for now. ## When to use it in APIs Never. It has no semantics in HTTP, so no client can act on it. If you want an easter egg, keep it out of any endpoint a real client calls. ## How it compares to other codes * **400 Bad Request**: Standard error representation for real client issues. --- # 421 Misdirected Request > The request was directed at a server that is not able to produce a response. Source: https://apiguide.dev/status-codes/421 Class: client-error Defined in: RFC 9110, Section 15.5.20 Updated: 2026-07-09 ## What does HTTP status code 421 mean? The 421 Misdirected Request status code indicates that the client directed its request to a server that is unable to generate a response for the combination of scheme and authority in the request. ## When to use it in APIs Useful in HTTP/2 and HTTP/3 settings, where connections are commonly reused (coalesced) across multiple hostnames that share an IP address and TLS certificate. If a client reuses such a connection to request a hostname the server isn't actually configured to serve, the server returns 421 to tell the client to retry on a fresh connection instead. ## How it compares to other codes * **404 Not Found**: Implies the path doesn't exist on this host, whereas 421 implies the request reached the wrong host entirely. --- # 422 Unprocessable Content > The request body was syntactically correct but failed semantic business rules validation. Source: https://apiguide.dev/status-codes/422 Class: client-error Defined in: RFC 9110, Section 15.5.21 Updated: 2026-10-14 ## What does HTTP status code 422 mean? The 422 Unprocessable Content status code (titled "Unprocessable Entity" before RFC 9110) indicates that the server understands the content type and syntax of the request, but cannot process the contained instructions due to semantic validation failures. ## When to use it in APIs The primary status code for input validation failures. Use 422 when required fields are missing, strings fail regex constraints, or numbers fall out of range. ## How it compares to other codes * **400 Bad Request**: Use 400 when the JSON is malformed and cannot be parsed. Use 422 when the JSON parses successfully but has validation errors. --- # 423 Locked > The resource that is being accessed is locked. Source: https://apiguide.dev/status-codes/423 Class: client-error Defined in: RFC 4918 Updated: 2026-07-09 ## What does HTTP status code 423 mean? The 423 Locked status code (from WebDAV, RFC 4918) indicates that the target resource is currently locked and cannot be modified. ## When to use it in APIs Use when a tenant resource has been locked by administrators (due to billing freeze, moderation, etc.) or when a resource is temporarily locked for editing. ## How it compares to other codes * **403 Forbidden**: A general permission denial. 423 indicates permission is denied specifically because of a lock state. --- # 424 Failed Dependency > The request failed because it depended on another action that failed. Source: https://apiguide.dev/status-codes/424 Class: client-error Defined in: RFC 4918 Updated: 2026-07-09 ## What does HTTP status code 424 mean? The 424 Failed Dependency status code (from WebDAV, RFC 4918) indicates that the request was omitted because the action depended on another action that failed. ## When to use it in APIs Useful in batch transactional endpoints. If a client submits a batch of operations, and transaction A fails, transaction B (which depends on A) fails with a 424. ## How it compares to other codes * **400 Bad Request**: A general request failure, whereas 424 specifies that the request itself was okay but was blocked by an external step failure. --- # 425 Too Early > The server is unwilling to risk processing a request that might be replayed. Source: https://apiguide.dev/status-codes/425 Class: client-error Defined in: RFC 8470 Updated: 2026-10-14 ## What does HTTP status code 425 mean? The 425 Too Early status code, defined in RFC 8470, indicates that the server is unwilling to risk processing a request that might be replayed. It applies to requests sent in TLS 1.3 early data (0-RTT), which an attacker can capture and resend. User agents are expected to retry after a 425, and RFC 8470 requires that the retry is not sent in early data. ## When to use it in APIs Return it when a request arrived in early data, directly or marked by an intermediary with [`Early-Data: 1`](/headers/early-data), and processing a replayed copy would cause a side effect. RFC 8470 says a server should not send 425 unless one of those two conditions holds, because otherwise it cannot assume the client is able to retry. Do not think of it as protection for `POST` endpoints. Absent other information, RFC 8470 forbids clients from sending unsafe methods in early data, so a `POST` to a payments endpoint should not arrive there in the first place (if one does, reject it with 425 too). The realistic risk is a request the client treated as safe, such as a `GET`, that has a side effect on your server: consuming a single-use link, triggering a one-time action or counting against a metered quota. Decide per route whether early data is acceptable, and answer 425 on the routes where it is not. ## How it compares to other codes * **400 Bad Request**: The request itself is wrong and resending it unchanged fails again. A 425 request is fine; resending it after the handshake succeeds. * **409 Conflict**: The request conflicts with current resource state. 425 is about how the request was delivered, not what it asks for. * **503 Service Unavailable**: The server cannot handle any request right now. 425 refuses only this request in early data, and the retry can be sent immediately once the handshake completes. --- # 426 Upgrade Required > The server refuses to perform the request using the current protocol. Source: https://apiguide.dev/status-codes/426 Class: client-error Defined in: RFC 9110, Section 15.5.22 Updated: 2026-07-09 ## What does HTTP status code 426 mean? The 426 Upgrade Required status code indicates that the server refuses to execute the request unless the client upgrades to a newer protocol (like HTTP/2 or TLS 1.3). ## When to use it in APIs Used to force old API clients or mobile apps to update their connection libraries to support secure protocols. ## How it compares to other codes * **101 Switching Protocols**: An agreement by the server to switch. 426 is a *requirement* that the client upgrade before proceed. --- # 428 Precondition Required > The origin server requires the request to be conditional. Source: https://apiguide.dev/status-codes/428 Class: client-error Defined in: RFC 6585 Updated: 2026-07-09 ## What does HTTP status code 428 mean? The 428 Precondition Required status code indicates that the server requires the request to be conditional (using headers like If-Match or If-Modified-Since). ## When to use it in APIs Used to prevent the "lost update" problem. The server refuses updates unless the client explicitly sends a version header constraint, forcing them to acknowledge the version state. ## How it compares to other codes * **412 Precondition Failed**: Returned when the precondition check *fails*. 428 is returned when the precondition check was *omitted* entirely. --- # 429 Too Many Requests > The user has sent too many requests in a given amount of time. Source: https://apiguide.dev/status-codes/429 Class: client-error Defined in: RFC 6585 Updated: 2026-10-14 ## What does HTTP status code 429 mean? The 429 Too Many Requests status code indicates that the client has exceeded their allowed rate limits or quotas. ## When to use it in APIs Standard response for rate limiters. Include [`Retry-After`](/headers/retry-after) to say when to try again, and the [`RateLimit`](/headers/ratelimit) and [`RateLimit-Policy`](/headers/ratelimit-policy) fields to show the remaining quota and the policy that was exceeded. ## How it compares to other codes * **503 Service Unavailable**: Represents a server-side capacity outage. 429 represents a client-side quota violation. --- # 431 Request Header Fields Too Large > The server refuses to process the request because header fields are too large. Source: https://apiguide.dev/status-codes/431 Class: client-error Defined in: RFC 6585 Updated: 2026-07-09 ## What does HTTP status code 431 mean? The 431 Request Header Fields Too Large status code indicates that the server rejects the request because the headers (or a single header field) are too large. ## When to use it in APIs Usually triggered when a client sends extremely large cookies, authorization tokens (like bloated JWTs), or request parameters. ## How it compares to other codes * **400 Bad Request**: A generic request failure. 431 explicitly points to header size violations. --- # 451 Unavailable For Legal Reasons > The server operator has received a legal demand to deny access to the resource. Source: https://apiguide.dev/status-codes/451 Class: client-error Defined in: RFC 7725 Updated: 2026-07-09 ## What does HTTP status code 451 mean? The 451 Unavailable For Legal Reasons status code (RFC 7725) indicates that the resource is inaccessible due to legal demands (e.g. copyright takedowns, censorship, or court orders). ## When to use it in APIs Use when regional censorship, licensing limits, or court-mandated takedowns block API access to certain data subsets. ## How it compares to other codes * **403 Forbidden**: A general permission failure. 451 is an explicit disclosure of legal restriction. --- # 500 Internal Server Error > The server encountered an unexpected condition that prevented it from fulfilling the request. Source: https://apiguide.dev/status-codes/500 Class: server-error Defined in: RFC 9110, Section 15.6.1 Updated: 2026-07-09 ## What does HTTP status code 500 mean? The 500 Internal Server Error status code is the generic fallback error returned when the server encounters an unhandled exception or system failure. ## When to use it in APIs Returned automatically by application frameworks when code bugs, database server outages, or unhandled exceptions occur. Sanitized details should be logged, and a clean response returned. ## How it compares to other codes * **502 Bad Gateway**: Implies a proxy gateway received an invalid response from an upstream application node. 500 represents a direct application crash. --- # 501 Not Implemented > The server does not support the functionality required to fulfill the request. Source: https://apiguide.dev/status-codes/501 Class: server-error Defined in: RFC 9110, Section 15.6.2 Updated: 2026-07-09 ## What does HTTP status code 501 mean? The 501 Not Implemented status code indicates that the server does not support or recognize the request method or capability. ## When to use it in APIs Used when stubbing out new endpoints or when an API does not support certain standard HTTP operations (like a read-only API receiving a DELETE request). ## How it compares to other codes * **405 Method Not Allowed**: Implies the method *is* recognized by the server but is not permitted on that specific route. 501 implies the server lacks the capacity to perform the method globally. --- # 502 Bad Gateway > An upstream server returned an invalid response to the gateway proxy. Source: https://apiguide.dev/status-codes/502 Class: server-error Defined in: RFC 9110, Section 15.6.3 Updated: 2026-10-17 ## What does HTTP status code 502 mean? The 502 Bad Gateway status code indicates that the proxy server or gateway received an invalid or empty response from the backend application process. ## When to use it in APIs Typically generated by Nginx, Cloudflare, or AWS ALBs when the backend application node (e.g., Node.js, Python, or Go process) crashes, returns invalid headers, or is offline. Have the gateway add a [`Proxy-Status`](/headers/proxy-status) header naming the cause, such as `error=connection_refused` or `error=dns_error`, so you can tell those failures apart without digging through gateway logs. ## How it compares to other codes * **504 Gateway Timeout**: The backend responded but took too long. 502 indicates the backend responded with garbage or terminated the connection immediately. --- # 503 Service Unavailable > The server is temporarily down or overloaded. The client should retry. Source: https://apiguide.dev/status-codes/503 Class: server-error Defined in: RFC 9110, Section 15.6.4 Updated: 2026-07-09 ## What does HTTP status code 503 mean? The 503 Service Unavailable status code indicates that the server is temporarily unable to process the request due to planned maintenance or severe overload. ## When to use it in APIs Use during deployments, maintenance windows, or when database connection pools are exhausted. Always include a `Retry-After` header. ## How it compares to other codes * **429 Too Many Requests**: Triggered when a *specific* client exceeds their quota. 503 is returned when the *system* itself is overloaded globally. --- # 504 Gateway Timeout > The upstream server failed to send a timely response to the gateway proxy. Source: https://apiguide.dev/status-codes/504 Class: server-error Defined in: RFC 9110, Section 15.6.5 Updated: 2026-10-17 ## What does HTTP status code 504 mean? The 504 Gateway Timeout status code indicates that a proxy server or gateway timed out waiting for a response from the backend application node. ## When to use it in APIs Generated by gateways when heavy queries, long-running processes, or external API dependencies block the execution thread beyond connection limits. A [`Proxy-Status`](/headers/proxy-status) header from the gateway says which wait expired, such as `error=connection_timeout` or `error=http_response_timeout`. ## How it compares to other codes * **502 Bad Gateway**: Means the backend returned an invalid response quickly. 504 means the backend took too long to return anything. --- # 505 HTTP Version Not Supported > The server does not support the HTTP protocol version used in the request. Source: https://apiguide.dev/status-codes/505 Class: server-error Defined in: RFC 9110, Section 15.6.6 Updated: 2026-07-09 ## What does HTTP status code 505 mean? The 505 HTTP Version Not Supported status code indicates that the server does not support the major HTTP version (like HTTP/3) used by the client. ## When to use it in APIs Enforced by load balancers or application hosts when receiving unsupported HTTP versions. ## How it compares to other codes * **426 Upgrade Required**: Rejects a request because the connection must first be upgraded to a different protocol version (e.g. HTTP/1.1 to HTTP/2, or to a WebSocket), whereas 505 rejects a request because the version the client already sent isn't supported at all. --- # 506 Variant Also Negotiates > Content negotiation for the request results in a circular reference. Source: https://apiguide.dev/status-codes/506 Class: server-error Defined in: RFC 2295 Updated: 2026-07-09 ## What does HTTP status code 506 mean? The 506 Variant Also Negotiates status code indicates that the server has a configuration error where content negotiation results in a circular loop. ## When to use it in APIs Rarely used; indicates server configuration issues where resources attempt to negotiate formats with themselves. ## How it compares to other codes * **500 Internal Server Error**: A generic application code failure, whereas 506 is configuration-negotiation specific. --- # 507 Insufficient Storage > The server is unable to store the representation needed to complete the request. Source: https://apiguide.dev/status-codes/507 Class: server-error Defined in: RFC 4918 Updated: 2026-07-09 ## What does HTTP status code 507 mean? The 507 Insufficient Storage status code (WebDAV, RFC 4918) indicates that the server cannot complete the request because it lacks disk space. ## When to use it in APIs Useful for storage or upload APIs to explicitly notify users that a file upload was rejected because the server has run out of physical disk space. ## How it compares to other codes * **500 Internal Server Error**: Generic failure. 507 points directly to storage limit issues. --- # 508 Loop Detected > The server terminated the operation because it detected an infinite loop. Source: https://apiguide.dev/status-codes/508 Class: server-error Defined in: RFC 5842 Updated: 2026-07-09 ## What does HTTP status code 508 mean? The 508 Loop Detected status code (WebDAV, RFC 5842) indicates that the server aborted the operation because it detected an infinite redirection loop. ## When to use it in APIs Used in WebDAV settings or complex hierarchical resource resolution where links form a loop. ## How it compares to other codes * **500 Internal Server Error**: A generic server failure, whereas 508 is specifically a loop resolution abort. --- # 510 Not Extended > Further extensions to the request are required for the server to fulfill it. Source: https://apiguide.dev/status-codes/510 Class: server-error Defined in: RFC 2774 Updated: 2026-10-14 ## What does HTTP status code 510 mean? The 510 Not Extended status code (RFC 2774) indicates that the server requires further protocol extensions to complete the request. RFC 2774, the HTTP Extension Framework, has since been moved to Historic, and the IANA registry marks 510 as obsoleted. ## When to use it in APIs Do not use it. The extension framework it belongs to is obsolete, so clients have no defined way to respond to it. ## How it compares to other codes * **500 Internal Server Error**: Represents standard application failures. --- # 511 Network Authentication Required > The client needs to authenticate to gain network access. Source: https://apiguide.dev/status-codes/511 Class: server-error Defined in: RFC 6585 Updated: 2026-07-09 ## What does HTTP status code 511 mean? The 511 Network Authentication Required status code indicates that the client must authenticate to gain network access (e.g., captive portals). ## When to use it in APIs Typically generated by public Wi-Fi networks or proxies before letting request traffic through to the internet. ## How it compares to other codes * **401 Unauthorized**: Identifies authentication needed for the target API host, whereas 511 is for access to the network itself. --- # Accept header > Specifies the media types that the client is willing to receive in the response. Source: https://apiguide.dev/headers/accept Direction: request Standardized: yes Defined in: RFC 9110, Section 12.5.1 Updated: 2026-07-08 ## What is the Accept header? The `Accept` request header tells the server which media types (like JSON, XML, or HTML) the client is able to process. It enables content negotiation, allowing the same URL to serve different formats depending on client capability. ## API Usage & Best Practices * **Always require it in strict APIs**: If your API only supports JSON, validate that the client accepts JSON. * **Fallback gracefully**: If the client specifies an Accept value your API cannot satisfy, return a `406 Not Acceptable` response. ## Examples ```http GET /v1/leads HTTP/1.1 Host: api.apiguide.dev Accept: application/json ``` --- # Accept-Encoding header > Declares what compression algorithms the client supports for the response payload. Source: https://apiguide.dev/headers/accept-encoding Direction: request Standardized: yes Defined in: RFC 9110, Section 12.5.3 Updated: 2026-07-08 ## What is the Accept-Encoding header? The `Accept-Encoding` request header advertises the compression formats (such as `gzip`, `deflate`, or `br` for Brotli) that the client is capable of decoding. ## API Usage & Best Practices * **Enable compression at the gateway**: Ensure your API gateway or web server (Nginx, Cloudflare) automatically compresses JSON payloads using the best algorithm supported by the client. * **Significant performance gains**: Compressing JSON responses can reduce payload size by up to 70-80% for large lists. ## Examples ```http GET /v1/leads HTTP/1.1 Host: api.apiguide.dev Accept-Encoding: gzip, deflate, br ``` --- # Accept-Language header > Advertises the natural languages the client prefers for the response. Source: https://apiguide.dev/headers/accept-language Direction: request Standardized: yes Defined in: RFC 9110, Section 12.5.4 Updated: 2026-07-10 ## What is the Accept-Language header? The `Accept-Language` request header tells the server which natural languages the client prefers, using language tags with optional quality (`q`) values to express relative preference. The server uses it during content negotiation to choose a language variant. ## API Usage & Best Practices * **Use q-values to rank**: A weight from `0` to `1` orders preferences, for example `fr-CH, fr;q=0.9, en;q=0.8`. * **Handle unsupported languages**: If no acceptable language can be served, the server may respond with `406 Not Acceptable`, though returning a sensible default is often friendlier. * **Confirm with `Content-Language`**: The chosen variant should be echoed back in the response's `Content-Language` header. ## Examples ```http GET /articles/42 HTTP/1.1 Host: api.example.com Accept-Language: fr-CH, fr;q=0.9, en;q=0.8, *;q=0.5 ``` --- # Accept-Patch header > Advertises which patch document media types a resource accepts in PATCH requests, and by its presence that PATCH is allowed at all. Source: https://apiguide.dev/headers/accept-patch Direction: response Standardized: yes Defined in: RFC 5789 Updated: 2026-10-14 ## What is the Accept-Patch header? The `Accept-Patch` response header, defined in Section 3.1 of [RFC 5789](https://www.rfc-editor.org/rfc/rfc5789.html) alongside the [`PATCH`](/methods/patch) method, lists the patch document formats a resource accepts. Its value is a comma-separated list of media types, with optional parameters: ```http Accept-Patch: application/merge-patch+json, application/json-patch+json ``` A `PATCH` body is not the new state of the resource, it is a set of instructions for changing it, and its media type decides how those instructions are read. The same JSON object means something different as a [JSON Merge Patch](/specifications/json-merge-patch) (`application/merge-patch+json`, RFC 7396) than it does as a [JSON Patch](/specifications/json-patch) (`application/json-patch+json`, RFC 6902). `Accept-Patch` is how a client finds out which interpretations the server supports before it sends one. RFC 5789 gives the header two meanings: the presence of `Accept-Patch` on a response to any method implies that `PATCH` is allowed on that resource, and each listed type is one the resource will accept. ## API Usage & Best Practices * **Send it on `OPTIONS` for every patchable resource.** RFC 5789 says it SHOULD appear in the [`OPTIONS`](/methods/options) response for any resource that supports `PATCH`, next to an [`Allow`](/headers/allow) header listing `PATCH`. * **Send it on `415` responses.** When a client sends a patch format you do not support, answer [`415 Unsupported Media Type`](/status-codes/415) with `Accept-Patch` listing what you do support. RFC 5789 Section 2.2 says such a response SHOULD include it, and it turns a dead end into a one-step fix. * **Do not list `application/json` as a patch format.** Plain JSON has no defined patch semantics, so a server that accepts it has invented its own, and a client cannot tell from the header which one. Accept `application/merge-patch+json` for simple field updates and `application/json-patch+json` when clients need array operations or tests, and say so explicitly. * **Only list a type on a resource that really takes it.** Its presence is a promise that `PATCH` works. Do not emit a blanket `Accept-Patch` on read-only resources or on collections that only take [`POST`](/methods/post). * **Keep it out of `Accept`.** [`Accept`](/headers/accept) is a request header about response formats. `Accept-Patch` is a response header about request formats. They answer different questions, and its sibling for `POST` is [`Accept-Post`](/headers/accept-post). * **Reject malformed patches with `400`, unprocessable ones with `422`.** RFC 5789 distinguishes a badly formatted patch document ([`400 Bad Request`](/status-codes/400)) from a valid one that cannot be applied ([`422 Unprocessable Content`](/status-codes/422)), and a failed `If-Match` precondition from both ([`412 Precondition Failed`](/status-codes/412)). See [PATCH strategies](/guides/patch-strategies). ## Examples Discovering what a resource accepts before patching it: ```http OPTIONS /v1/users/42 HTTP/1.1 Host: api.example.com ``` ```http HTTP/1.1 204 No Content Allow: GET, PUT, PATCH, DELETE, OPTIONS, HEAD Accept-Patch: application/merge-patch+json, application/json-patch+json ``` A client sent plain JSON and was told which formats would have worked: ```http HTTP/1.1 415 Unsupported Media Type Content-Type: application/problem+json Accept-Patch: application/merge-patch+json, application/json-patch+json { "type": "https://apiguide.dev/errors/unsupported-media-type", "title": "Unsupported Media Type", "status": 415, "detail": "PATCH bodies must be application/merge-patch+json or application/json-patch+json." } ``` --- # Accept-Post header > Advertises which media types a resource accepts in POST requests, modeled on Accept-Patch and defined by the W3C Linked Data Platform. Source: https://apiguide.dev/headers/accept-post Direction: response Standardized: yes Defined in: W3C Linked Data Platform 1.0 Updated: 2026-10-14 ## What is the Accept-Post header? The `Accept-Post` response header lists the media types a resource will accept as the body of a [`POST`](/methods/post) request. It was defined in Section 7.1 of the W3C Recommendation [Linked Data Platform 1.0](https://www.w3.org/TR/ldp/) (LDP, February 2015), is registered as a permanent field in the IANA HTTP Field Name Registry with that specification as its reference, and is deliberately modeled on [`Accept-Patch`](/headers/accept-patch). Its value is a comma-separated list of media ranges, with the same syntax as [`Accept`](/headers/accept) minus the `q` weights, which have no meaning here: ```http Accept-Post: application/json, multipart/form-data ``` LDP gives it the same two meanings `Accept-Patch` has: the header's presence on a response to any method implies that `POST` is allowed on the resource, and each listed type is one the resource accepts. Although it was written for LDP containers, nothing in its definition is specific to RDF, and LDP itself notes it applies beyond LDP. ## API Usage & Best Practices * **Send it where `POST` creates things.** A collection endpoint that accepts new members is the natural place. Include it on [`OPTIONS`](/methods/options) responses, which LDP says it SHOULD appear on for any resource supporting `POST`, and optionally on `GET` and `HEAD` so a client discovers it without an extra round trip. * **Send it on `415` responses.** When a client posts a body in a format you do not accept, answer [`415 Unsupported Media Type`](/status-codes/415) and list what you do accept. RFC 9110 suggests [`Accept`](/headers/accept) in a `415` response for this purpose; `Accept-Post` is the more precise of the two because it is scoped to `POST`, and sending both does no harm. * **List what you validate, not what you parse.** If the endpoint accepts `application/json` only when it matches one schema, the header cannot say so. Keep it truthful at the media type level and document the schema in your [OpenAPI](/specifications/openapi) description. * **Use media ranges sparingly.** `image/*` is legitimate for an upload endpoint that really accepts any image format. `*/*` tells the client nothing and should not be sent. * **Do not make it the contract.** Treat it as a hint for discovery and error recovery. A client cannot learn your schemas, size limits or required fields from it, so the contract stays in your API description. ## Examples A collection advertising the formats it accepts for new members: ```http OPTIONS /v1/documents HTTP/1.1 Host: api.example.com ``` ```http HTTP/1.1 204 No Content Allow: GET, POST, OPTIONS, HEAD Accept-Post: application/json, multipart/form-data ``` An upload endpoint rejecting a format it does not take: ```http HTTP/1.1 415 Unsupported Media Type Content-Type: application/problem+json Accept-Post: image/png, image/jpeg, image/webp { "type": "https://apiguide.dev/errors/unsupported-media-type", "title": "Unsupported Media Type", "status": 415, "detail": "Avatars must be PNG, JPEG or WebP." } ``` --- # Accept-Query header > Signals that a resource supports the QUERY method and lists the query formats it accepts, as a Structured Field list of media types. Source: https://apiguide.dev/headers/accept-query Direction: response Standardized: yes Defined in: RFC 10008, Section 3 Updated: 2026-10-14 ## What is the Accept-Query header? The `Accept-Query` response header, defined in Section 3 of [RFC 10008](https://www.rfc-editor.org/rfc/rfc10008.html) (The HTTP QUERY Method, Standards Track, June 2026), tells a client two things at once: that the resource supports the [`QUERY`](/methods/query) method, and which media types it accepts as query content. A `QUERY` request carries its query in the body, and the body's [`Content-Type`](/headers/content-type) decides how it is interpreted: a form-encoded filter, a JSONPath expression, SQL. `Accept-Query` is how the server advertises which of those it understands, in the same way [`Accept-Patch`](/headers/accept-patch) does for `PATCH`. Unlike `Accept-Patch`, it is a [Structured Field](/specifications/structured-fields): a List whose members are media ranges written as Tokens or Strings, with media type parameters mapped to Structured Field parameters. ```http Accept-Query: "application/jsonpath", application/sql;charset="UTF-8" ``` Points from RFC 10008 Section 3 that differ from `Accept` and catch people out: - **Token or String is your choice, and means the same.** Recipients must not treat them differently. A media type that is not a valid Token (one beginning with a digit, for example) has to be a String. - **Order is not significant**, and there are no `q` weights. - **Wildcards are limited** to `*/*` and `type/*`. - **It applies to the path, not the full URI.** The value covers every URI on the server sharing the same path; the query component is ignored. If responses disagree, the most recently received fresh value wins. ## API Usage & Best Practices * **Parse it as a Structured Field, not with your `Accept` parser.** RFC 10008 requires processing per RFC 9651. An `Accept` parser will mishandle the quoted strings and parameters, and a hand-rolled split on commas will break on a quoted parameter value. * **Send it on `415` responses to `QUERY`.** RFC 10008 recommends [`415 Unsupported Media Type`](/status-codes/415) when the query's media type is not supported by the resource, including a type known in general but without query semantics there, and names `Accept-Query` as the way to tell the client what would work. * **Advertise it on `GET`, `HEAD` and `OPTIONS` too.** A client that wants to switch from `GET` to `QUERY` needs to learn that it can before it tries. RFC 10008 shows it on a `HEAD` response; pair it with `QUERY` in [`Allow`](/headers/allow) on [`OPTIONS`](/methods/options). * **Add it to `Vary` if it changes with the request.** The examples in RFC 10008 list `Accept-Query` in [`Vary`](/headers/vary) alongside `Content-Type` on cacheable `QUERY` responses. * **Only list formats with real query semantics.** Listing `application/json` is meaningless unless you define what a JSON query document means for that resource. Prefer a registered query format (`application/jsonpath`, `application/sql`) or a vendor media type you document. * **Check the path before relying on it.** QUERY was published as RFC 10008 in June 2026, and proxies, CDNs, gateways and client libraries that have not caught up may reject or mishandle an unknown method. Test the full path to your origin before you expose `QUERY` in a public contract, and keep a `POST` fallback for clients that cannot send it. ## Examples Discovering supported query formats with `HEAD`: ```http HEAD /v1/contacts HTTP/1.1 Host: api.example.com ``` ```http HTTP/1.1 200 OK Content-Type: application/json Accept-Query: application/x-www-form-urlencoded, "application/jsonpath" ``` A `QUERY` sent in a format the resource does not support: ```http QUERY /v1/contacts HTTP/1.1 Host: api.example.com Content-Type: application/sql Accept: application/json SELECT surname, email FROM contacts LIMIT 10 ``` ```http HTTP/1.1 415 Unsupported Media Type Content-Type: application/problem+json Accept-Query: application/x-www-form-urlencoded, "application/jsonpath" { "type": "https://apiguide.dev/errors/unsupported-media-type", "title": "Unsupported Media Type", "status": 415, "detail": "QUERY content must be application/x-www-form-urlencoded or application/jsonpath." } ``` --- # Accept-Ranges header > Advertises whether a server supports range requests for a resource. Source: https://apiguide.dev/headers/accept-ranges Direction: response Standardized: yes Defined in: RFC 9110, Section 14.3 Updated: 2026-07-10 ## What is the Accept-Ranges header? The `Accept-Ranges` response header tells the client whether the server supports partial requests for a resource, and which unit those ranges are measured in. The value `bytes` signals support, while `none` explicitly indicates that ranges are not supported. ## API Usage & Best Practices * **Enables resumable transfers**: When a client sees `Accept-Ranges: bytes`, it knows it can safely send a `Range` header to resume a download or stream a portion of the resource. * **Be explicit about no support**: Returning `Accept-Ranges: none` discourages clients from attempting range requests that the server would only answer with the full body. ## Examples ```http HTTP/1.1 200 OK Content-Length: 146515 Accept-Ranges: bytes ``` --- # Accept-Signature header > Asks the other side to sign its message with RFC 9421 HTTP Message Signatures, naming the label, covered components and parameters. Source: https://apiguide.dev/headers/accept-signature Direction: both Standardized: yes Defined in: RFC 9421, Section 5.1 Updated: 2026-10-17 ## What is the Accept-Signature header? The `Accept-Signature` field, defined in Section 5.1 of [RFC 9421](https://www.rfc-editor.org/rfc/rfc9421.html) (HTTP Message Signatures), lets a potential verifier ask for a signature instead of waiting for one. Its direction decides which message it targets: * **In a request**, it asks the server to sign the response to that request. * **In a response**, it asks the client to sign its next request to the server. The client can choose to keep signing future requests the same way. It is a Dictionary [Structured Field](/specifications/structured-fields) with the same shape as [`Signature-Input`](/headers/signature-input). Each member's key is the label the requested signature must use, and its value is the list of covered components, with signature parameters: ```http Accept-Signature: sig1=("@method" "@target-uri" "@authority" "content-digest" "cache-control");keyid="test-key-rsa-pss";created;tag="app-123" ``` The parameters are requests to the signer. `created` and `expires` take no value here and ask the signer to include a creation or expiry time. `nonce`, `tag`, `alg` and `keyid` ask the signer to use the given nonce, tag, algorithm or key. The target message must carry every requested signature, under the requested label, covering exactly the requested components, with every requested parameter processed. The signer may add more parameters and more signatures. It may also ignore a request that does not fit its application. The answer arrives in [`Signature-Input`](/headers/signature-input) and [`Signature`](/headers/signature). ## API Usage & Best Practices * **Vary on it, or do not cache.** RFC 9421 says responses from resources that support signature negotiation SHOULD be uncacheable or carry [`Vary`](/headers/vary)`: Accept-Signature`. Otherwise a cache can serve one client's requested signature, with its nonce, to another client. * **Request only components the target message can have.** A request cannot contain `@status`, and a response has no `@method` of its own. The sender of `Accept-Signature` MUST include only identifiers that suit the target message. * **Use a nonce for responses you need to be fresh.** A client that asks for `nonce="..."` and checks it in the response knows the signature was made for this request, not replayed from an earlier one. * **Do not treat it as enforcement.** The receiver MAY ignore any request it cannot fulfill. If your API requires signed requests, reject unsigned ones with [`401 Unauthorized`](/status-codes/401) and document the profile. Sending `Accept-Signature` on that `401` is a useful way to tell the client exactly what to sign. * **Cover the body through a digest.** If you want the body signed, ask for `content-digest` among the components and expect a [`Content-Digest`](/headers/content-digest) on the message. Signatures do not cover content directly. * **Match on key and coverage, not label alone.** Labels are local to one message. When verifying, check that the signature under the label you asked for uses the expected key and covers what you asked for. ## Examples A client asking the server to sign the response, covering the status, content type and content digest, with a fresh creation time and a nonce it chose: ```http GET /v1/statements/stm_2026_09 HTTP/1.1 Host: api.example.com Accept-Signature: sig1=("@status" "content-type" "content-digest");created;keyid="server-key-2026";nonce="m4zpWCbNSDbqAFwr" ``` A server rejecting an unsigned request and telling the client how to sign the retry: ```http HTTP/1.1 401 Unauthorized Content-Type: application/problem+json Accept-Signature: sig1=("@method" "@target-uri" "content-digest" "content-type");created;keyid="client-key-17";alg="ed25519" { "type": "https://api.example.com/problems/signature-required", "title": "Signature required", "status": 401, "detail": "Sign the request as described in Accept-Signature." } ``` --- # Access-Control-Allow-Credentials header > Indicates whether the response can be exposed when the CORS request includes credentials. Source: https://apiguide.dev/headers/access-control-allow-credentials Direction: response Standardized: yes Defined in: WHATWG Fetch Standard Updated: 2026-07-10 ## What is the Access-Control-Allow-Credentials header? The `Access-Control-Allow-Credentials` response header tells the browser whether JavaScript may read the response when the cross-origin request was made with credentials such as cookies, TLS client certificates, or `Authorization` headers. Its only valid value is `true`. ## API Usage & Best Practices * **Requires an explicit origin**: When set to `true`, `Access-Control-Allow-Origin` must name a specific origin; the wildcard `*` is rejected by the browser for credentialed requests. * **Client must opt in too**: The header only has effect when the client sends the request with `credentials: 'include'` (Fetch) or `withCredentials = true` (XHR). * **Applies to headers too**: With credentials, wildcards in `Access-Control-Allow-Headers` and `Access-Control-Allow-Methods` are also ignored. ## Examples ```http HTTP/1.1 200 OK Access-Control-Allow-Origin: https://app.example.com Access-Control-Allow-Credentials: true ``` --- # Access-Control-Allow-Headers header > Lists the request headers that are permitted during the actual CORS request. Source: https://apiguide.dev/headers/access-control-allow-headers Direction: response Standardized: yes Defined in: WHATWG Fetch Standard Updated: 2026-07-10 ## What is the Access-Control-Allow-Headers header? The `Access-Control-Allow-Headers` response header is sent in reply to a CORS preflight to tell the browser which request headers may be used when making the actual cross-origin request. It answers the headers listed in `Access-Control-Request-Headers`. ## API Usage & Best Practices * **Preflight only**: It appears on the `OPTIONS` preflight response (usually `204 No Content`) and must cover any non-safelisted header your client sends, such as `Authorization` or `Content-Type: application/json`. * **Mirror the request**: A common pattern is to echo back the value of `Access-Control-Request-Headers`, though listing headers explicitly is more secure. The wildcard `*` is ignored for credentialed requests. ## Examples ```http HTTP/1.1 204 No Content Access-Control-Allow-Origin: https://app.example.com Access-Control-Allow-Headers: Authorization, Content-Type ``` --- # Access-Control-Allow-Methods header > Lists the HTTP methods permitted when accessing a resource in response to a CORS preflight. Source: https://apiguide.dev/headers/access-control-allow-methods Direction: response Standardized: yes Defined in: WHATWG Fetch Standard Updated: 2026-07-10 ## What is the Access-Control-Allow-Methods header? The `Access-Control-Allow-Methods` response header is sent in reply to a CORS preflight request to tell the browser which HTTP methods are allowed when making the actual cross-origin request. It answers the method announced in `Access-Control-Request-Method`. ## API Usage & Best Practices * **Preflight only**: This header is meaningful on the `OPTIONS` preflight response (typically `204 No Content`), not on the actual request's response. * **List real methods**: Include every method the endpoint supports, such as `GET, POST, PUT, DELETE`. The wildcard `*` is allowed but is ignored for requests that include credentials. ## Examples ```http HTTP/1.1 204 No Content Access-Control-Allow-Origin: https://app.example.com Access-Control-Allow-Methods: GET, POST, PUT, DELETE ``` --- # Access-Control-Allow-Origin header > Specifies which origin(s) are permitted to read the response in a CORS request. Source: https://apiguide.dev/headers/access-control-allow-origin Direction: response Standardized: yes Defined in: WHATWG Fetch Standard Updated: 2026-07-10 ## What is the Access-Control-Allow-Origin header? The `Access-Control-Allow-Origin` response header tells the browser which origin is allowed to read the response of a cross-origin request. It is either a single origin, the wildcard `*`, or the specific origin echoed back from the request's `Origin` header. ## API Usage & Best Practices * **Echo, don't hardcode `*` blindly**: For APIs serving multiple trusted apps, validate the incoming `Origin` against an allowlist and echo it back, adding `Vary: Origin` so caches stay correct. * **`*` blocks credentials**: The wildcard cannot be combined with `Access-Control-Allow-Credentials: true`; requests carrying cookies or auth headers require an explicit origin instead. * **Preflight and actual response**: Send it on both the preflight (`204`) and the actual `200` response, or the browser rejects the result. ## Examples ```http HTTP/1.1 200 OK Access-Control-Allow-Origin: https://app.example.com Vary: Origin ``` --- # Access-Control-Expose-Headers header > Lists the response headers that browsers are allowed to expose to client-side JavaScript. Source: https://apiguide.dev/headers/access-control-expose-headers Direction: response Standardized: yes Defined in: WHATWG Fetch Standard Updated: 2026-07-10 ## What is the Access-Control-Expose-Headers header? The `Access-Control-Expose-Headers` response header names which response headers JavaScript is permitted to read on a cross-origin request. Without it, scripts can only access a small CORS-safelisted set such as `Content-Type`, `Cache-Control`, and `Content-Language`. ## API Usage & Best Practices * **Expose custom headers**: List anything your client needs to read, such as `X-Total-Count` for pagination or a custom `X-Request-Id` for tracing. * **Sent on the actual response**: Unlike most CORS headers, this one belongs on the actual `200` response, not the preflight. The wildcard `*` exposes all headers but is ignored for credentialed requests. ## Examples ```http HTTP/1.1 200 OK Access-Control-Allow-Origin: https://app.example.com Access-Control-Expose-Headers: X-Total-Count, X-Request-Id ``` --- # Access-Control-Max-Age header > Specifies how long the results of a CORS preflight request can be cached by the browser. Source: https://apiguide.dev/headers/access-control-max-age Direction: response Standardized: yes Defined in: WHATWG Fetch Standard Updated: 2026-07-10 ## What is the Access-Control-Max-Age header? The `Access-Control-Max-Age` response header tells the browser how many seconds it may cache the result of a CORS preflight request, including the `Access-Control-Allow-Methods` and `Access-Control-Allow-Headers` values. While cached, the browser skips the preflight for matching requests. ## API Usage & Best Practices * **Cuts preflight round-trips**: A higher value reduces latency by avoiding a repeated `OPTIONS` request before each actual call. * **Mind browser caps**: Browsers enforce their own maximums; Chromium caps the value at 7200 seconds (2 hours) and Firefox at 86400 seconds (24 hours), so larger numbers are silently clamped. * **Preflight only**: This header belongs on the `OPTIONS` preflight response, typically `204 No Content`. ## Examples ```http HTTP/1.1 204 No Content Access-Control-Allow-Origin: https://app.example.com Access-Control-Max-Age: 600 ``` --- # Access-Control-Request-Headers header > Sent by the browser in a CORS preflight to announce the custom headers of the actual request. Source: https://apiguide.dev/headers/access-control-request-headers Direction: request Standardized: yes Defined in: WHATWG Fetch Standard Updated: 2026-07-10 ## What is the Access-Control-Request-Headers header? The `Access-Control-Request-Headers` request header is set automatically by the browser during a CORS preflight (`OPTIONS`) request. It lists the non-safelisted headers the actual cross-origin request intends to send, letting the server decide whether to allow them. ## API Usage & Best Practices * **Browser-controlled**: You cannot set this header yourself; the browser generates it when the upcoming request includes headers like `Authorization` or a custom `X-*` header. * **Answered by the server**: The server replies with `Access-Control-Allow-Headers` on the `204` preflight response to confirm which headers are permitted. ## Examples ```http OPTIONS /api/users HTTP/1.1 Host: api.example.com Origin: https://app.example.com Access-Control-Request-Method: POST Access-Control-Request-Headers: Authorization, Content-Type ``` --- # Access-Control-Request-Method header > Sent by the browser in a CORS preflight to announce the method of the actual request. Source: https://apiguide.dev/headers/access-control-request-method Direction: request Standardized: yes Defined in: WHATWG Fetch Standard Updated: 2026-07-10 ## What is the Access-Control-Request-Method header? The `Access-Control-Request-Method` request header is set automatically by the browser during a CORS preflight (`OPTIONS`) request. It tells the server which HTTP method the actual cross-origin request will use, so the server can decide whether to permit it. ## API Usage & Best Practices * **Browser-controlled**: You cannot set this header manually; the browser adds it to the preflight when the upcoming request uses a non-simple method like `PUT` or `DELETE`. * **Answered by the server**: The server replies with `Access-Control-Allow-Methods` on the `204` preflight response to confirm the method is allowed. ## Examples ```http OPTIONS /api/users/42 HTTP/1.1 Host: api.example.com Origin: https://app.example.com Access-Control-Request-Method: DELETE ``` --- # Age header > The time in seconds since a cached response was generated at the origin server. Source: https://apiguide.dev/headers/age Direction: response Standardized: yes Defined in: RFC 9111, Section 5.1 Updated: 2026-10-14 ## What is the Age header? The `Age` response header, defined in RFC 9111, gives the sender's estimate, in seconds, of the time since the response was generated or successfully validated at the origin server. It is added by caches and CDNs. RFC 9111 states that its presence implies the response was not generated or validated by the origin for this request, but the reverse does not hold: a response without `Age` may still have come from a cache that does not send it. ## API Usage & Best Practices * **Estimate freshness**: Comparing `Age` against the freshness lifetime from `Cache-Control: max-age` tells you how much of a cached response's usable life remains. * **Diagnose caching**: Any `Age` value, including `0`, means some cache on the path answered the request, which is useful when debugging why clients are seeing stale data. It does not say which cache; use [`Cache-Status`](/headers/cache-status) for that. ## Examples ```http HTTP/1.1 200 OK Cache-Control: max-age=3600 Age: 118 ``` --- # Allow header > Lists the HTTP methods supported by the target resource, on a 405 Method Not Allowed or a 2xx OPTIONS response. Source: https://apiguide.dev/headers/allow Direction: response Standardized: yes Defined in: RFC 9110, Section 10.2.1 Updated: 2026-07-09 ## What is the Allow header? The `Allow` response header lists the set of HTTP methods supported by a resource. It is required on any `405 Method Not Allowed` response, and is equally standard on a successful `OPTIONS` response, where it's the primary way a client discovers what a resource supports. ## API Usage & Best Practices * **Always send on 405**: When rejecting a request due to an unsupported method, always include `Allow: GET, POST, HEAD` (matching the supported methods for that path). * **Also send on OPTIONS**: A `200 OK` response to `OPTIONS` should carry the same header so clients can probe supported methods without triggering an error. * **Do not include trailing commas**: The methods should be comma-separated, like `GET, POST, PUT`. ## Examples ```http HTTP/1.1 405 Method Not Allowed Allow: GET, HEAD Content-Type: application/problem+json ``` --- # Alt-Svc header > Advertises another protocol, host or port where the same origin can be reached, which is how clients discover HTTP/3. Source: https://apiguide.dev/headers/alt-svc Direction: response Standardized: yes Defined in: RFC 7838 Updated: 2026-10-17 ## What is the Alt-Svc header? The `Alt-Svc` response header, defined in [RFC 7838](https://www.rfc-editor.org/rfc/rfc7838.html) (HTTP Alternative Services), tells the client that the same origin is also available somewhere else: over a different protocol, on a different port, or on a different host. Its most common use by far is advertising [HTTP/3](/specifications/http3): a server answering over HTTP/1.1 or [HTTP/2](/specifications/http2) sends `Alt-Svc: h3=":443"`, and a client that speaks HTTP/3 can switch to QUIC for later requests. The value is either the keyword `clear` or a comma-separated list of alternatives in the server's order of preference. Each alternative is an ALPN protocol ID and an authority (an optional host, then a colon and a port), followed by optional parameters: | Parameter | Meaning | | :--- | :--- | | `ma` | Max age: how many seconds the client may remember the alternative. The default is 24 hours (86400), measured from when the response was generated, so the response's [`Age`](/headers/age) is subtracted. | | `persist` | `persist=1` asks the client to keep the alternative across network changes. Without it, a client that notices a network change should drop the entry. | `clear` tells the client to forget every alternative it has cached for that origin. A new `Alt-Svc` value replaces the cached set rather than adding to it. A client using an alternative should send the `Alt-Used` request header naming the host and port it actually connected to. In HTTP/2, a server can send the same information in an `ALTSVC` frame instead of the header. ## API Usage & Best Practices * **It is a hint, never a redirect.** The origin does not change: the URL, the `Host`, cookies and same-origin rules all stay the same. The client may ignore the advertisement entirely, and many server-side HTTP clients do. Never depend on clients switching. * **Let your edge send it.** If your CDN or load balancer terminates HTTP/3, it usually adds `Alt-Svc` for you. Emitting it from the application as well risks advertising a protocol on a port where nothing listens. Advertise only what the edge actually serves. * **The alternative must be authenticated for the origin.** RFC 7838 requires the client to validate the alternative's certificate against the **origin's** host name, and to send SNI for the origin. An alternative on another host only works if that host presents a certificate valid for your API's name. Cleartext alternatives such as `h2c` cannot be used this way. * **Use a sensible `ma`.** The 24-hour default is fine for a stable deployment. Before you remove an alternative, lower `ma` well ahead of time, or send `clear`, so clients are not left trying a port that is gone. A client falls back to the origin if the alternative fails, but every failed attempt costs it time. * **Answer misrouted requests with 421.** If a request reaches an alternative that cannot serve that origin, return [`421 Misdirected Request`](/status-codes/421). RFC 7838 says the client must then remove that alternative from its cache, and it may retry the request on another connection. * **Expect DNS to take over discovery.** HTTPS DNS records (RFC 9460) can advertise HTTP/3 before the first connection, which `Alt-Svc` cannot. Many deployments send both. `Alt-Svc` remains the fallback when the DNS record is absent or the resolver does not return it. * **Do not use it for load balancing or failover.** Clients choose whether and when to use an alternative, and cache it for `ma` seconds. That is too loose and too sticky to steer traffic reliably. ## Examples Advertising HTTP/3 on the same host and port, remembered for a day: ```http HTTP/2 200 Content-Type: application/json Alt-Svc: h3=":443"; ma=86400 ``` HTTP/3 on a different port, with HTTP/2 on another host as a second choice: ```http HTTP/1.1 200 OK Alt-Svc: h3=":8443"; ma=3600, h2="alt.example.com:443"; ma=3600 ``` A later request sent over the HTTP/2 alternative on `alt.example.com`. The authority is still the origin: ```http GET /v1/orders HTTP/2 Host: api.example.com Alt-Used: alt.example.com ``` Telling clients to forget all alternatives before decommissioning them: ```http HTTP/1.1 200 OK Alt-Svc: clear ``` --- # Authentication-Info header > Returns scheme-specific information to the client after its credentials have been accepted, such as the next nonce in Digest authentication. Source: https://apiguide.dev/headers/authentication-info Direction: response Standardized: yes Defined in: RFC 9110, Section 11.6.3 Updated: 2026-10-14 ## What is the Authentication-Info header? The `Authentication-Info` response header, defined in RFC 9110 Section 11.6.3, lets an HTTP authentication scheme send information back to the client once its credentials have been accepted. That can be a finalization message, such as the server proving its own identity. RFC 9110 defines only the generic format, a list of `name=value` parameters; each scheme defines which parameters exist and what they mean, based on the scheme named in the request's [`Authorization`](/headers/authorization) header. It can appear on any response regardless of method or status code, and it can be sent as a trailer field when the scheme explicitly allows it. A proxy forwarding the response MUST NOT modify it. Its proxy counterpart is `Proxy-Authentication-Info`, which works the same way for [`Proxy-Authorization`](/headers/proxy-authorization) but applies only to the next outbound client. ## API Usage & Best Practices * **You will rarely need it**: `Bearer` tokens (RFC 6750), API keys and `Basic` do not define any `Authentication-Info` parameters. The best-known user is HTTP Digest (RFC 7616 Section 3.5), which defines `nextnonce`, `qop`, `rspauth`, `cnonce` and `nc`. If your API uses bearer tokens, do not invent parameters for it. * **Do not use it to hand out new tokens**: Token refresh belongs in your token endpoint's response body, as [OAuth 2.0](/specifications/oauth2) does it, not in an ad hoc header on every response. Credentials in response headers get logged by proxies and observability tools. * **Mind the pipelining cost of `nextnonce`**: RFC 7616 warns that requiring a fresh nonce on every request prevents pipelining, and suggests the `nc` counter as a way to keep most of the security benefit without that cost. * **Read it if your scheme defines it**: A Digest client that ignores `nextnonce` may be asked to re-authenticate with `stale=true`, costing an extra round trip. ## Examples A Digest server rotating the nonce and proving its identity with `rspauth` (illustrative values): ```http HTTP/1.1 200 OK Content-Type: application/json Authentication-Info: nextnonce="5ccc069c403ebaf9f0171e9517f40e41", qop=auth, rspauth="6629fae49393a05397450978507c4ef1", cnonce="0a4f113b", nc=00000001 ``` --- # Authorization header > Contains the credentials to authenticate the client with the server. Source: https://apiguide.dev/headers/authorization Direction: request Standardized: yes Defined in: RFC 9110, Section 11.6.2 Updated: 2026-07-10 ## What is the Authorization header? The `Authorization` request header carries credentials that authenticate the client request, granting access to protected API endpoints. ## API Usage & Best Practices * **Use the Bearer scheme**: For modern token-based APIs (JWTs, OAuth2, API Keys), format the header as `Bearer `. * **Never transmit sensitive keys in query strings**: Always pass credentials in the `Authorization` header to prevent them from being logged in proxy servers. * **Shared caches skip authenticated responses**: Per RFC 9111, a shared cache (like a CDN) must not store a response to a request that carried an `Authorization` header unless the response explicitly opts in with a directive such as `public`, `must-revalidate`, or `s-maxage`. ## Examples ```http GET /v1/leads HTTP/1.1 Host: api.apiguide.dev Authorization: Bearer api_key_abc123xyz ``` --- # Cache-Control header > Directives for caching mechanisms in both requests and responses. Source: https://apiguide.dev/headers/cache-control Direction: both Standardized: yes Defined in: RFC 9111, Section 5.2 Updated: 2026-10-14 ## What is the Cache-Control header? The `Cache-Control` header specifies instructions for caching in both client browsers and intermediary proxies (like CDNs). ## API Usage & Best Practices * **Sensitive or per-user data: `no-store` on its own**: `no-store` forbids every cache, private and shared, from storing the response. Adding `no-cache`, `must-revalidate` or `max-age=0` to it changes nothing for a cache that follows RFC 9111, so send `Cache-Control: no-store` and stop there. * **Per-user data the browser may keep: `private`**: `private` lets the client's own cache store the response but keeps it out of shared caches such as CDNs and proxies. Pair it with `max-age` for a freshness window, or with `no-cache` to make the client revalidate with its [`ETag`](/headers/etag) on every use. * **Shared data: `max-age` plus `s-maxage`**: For responses that are the same for every caller (country lists, public configuration), use `public, max-age=60, s-maxage=86400`. `s-maxage` overrides `max-age` for shared caches only, so the CDN can hold the response longer than browsers do. A shared cache will not reuse a response to a request with an `Authorization` header unless it carries `public`, `s-maxage` or `must-revalidate`. * **Mutations need nothing extra**: RFC 9110 makes responses to `PUT` and `DELETE` non-cacheable, and a `POST` response is cacheable only with explicit freshness information and a matching [`Content-Location`](/headers/content-location). You do not need to decorate write responses to keep them out of caches. * **Target the CDN separately**: To give your CDN different instructions from browsers without touching `Cache-Control`, use [`CDN-Cache-Control`](/headers/cdn-cache-control). To see what a cache actually did with a response, read [`Cache-Status`](/headers/cache-status). ## Examples A per-user response no cache should store: ```http HTTP/1.1 200 OK Cache-Control: no-store ``` A shared response, cached briefly by browsers and for a day by the CDN: ```http HTTP/1.1 200 OK Cache-Control: public, max-age=60, s-maxage=86400 ``` --- # Cache-Group-Invalidation header > Sent on a response to an unsafe request, it asks caches to invalidate stored responses in the named cache groups. Source: https://apiguide.dev/headers/cache-group-invalidation Direction: response Standardized: yes Defined in: RFC 9875 Updated: 2026-10-17 ## What is the Cache-Group-Invalidation header? The `Cache-Group-Invalidation` response header, defined in Section 3 of [RFC 9875](https://www.rfc-editor.org/rfc/rfc9875.html) (HTTP Cache Groups, Standards Track, October 2025), lets the response to a state-changing request say which cache groups it has made stale. A cache that sees it MAY invalidate every stored response from the same origin that belongs to any listed group, as set by [`Cache-Groups`](/headers/cache-groups). The value is a [Structured Field](/specifications/structured-fields) List of Strings, each naming a group. Order does not matter and unrecognized parameters are ignored. ```http Cache-Group-Invalidation: "eurovision-results", "australia" ``` It MUST be ignored on responses to requests with a safe method, such as [`GET`](/methods/get) or [`HEAD`](/methods/head). Only responses to unsafe requests, such as [`POST`](/methods/post), [`PUT`](/methods/put), [`PATCH`](/methods/patch) and [`DELETE`](/methods/delete), can trigger it. Like grouped invalidation in general, it does not cascade. ## API Usage & Best Practices * **Send it from the write, naming what the write touched.** If updating a product changes the product page, the category listing and search results, put all of those groups in the response to the update. HTTP already invalidates the target URI of an unsafe request; this header reaches the related responses that HTTP caching cannot otherwise know about. See [cache invalidation](/guides/cache-invalidation). * **Do not send it on a `GET`.** It will be ignored, by design, so a read cannot be used to flush a cache. * **It only reaches caches the response passes through.** A browser cache or a reverse proxy in the response path can act on it. A CDN edge in another region, or a cache that never saw this response, will not. For those, use your CDN's purge API, and keep sensible freshness lifetimes as the backstop. * **Treat it as a hint.** Caches MAY act on it, and RFC 9875 notes that cache extensions such as targeted cache control (RFC 9213) could make it a requirement for the caches they address. Until your cache documents support, verify invalidation actually happens before relying on it. * **Stay within the interoperable limits.** Implementations MUST support at least 32 groups per field value, each at least 32 characters long. * **Restrict it on shared origins.** Any resource on an origin can invalidate any group on that origin, so on shared hosting one party can flush another's cache entries. ## Examples A response to a `POST` that affects two groups, from RFC 9875: ```http HTTP/1.1 200 OK Content-Type: text/html Cache-Group-Invalidation: "eurovision-results", "australia" ``` An API update invalidating the product and its category: ```http PATCH /v1/products/8812 HTTP/1.1 Host: api.example.com Content-Type: application/merge-patch+json {"price": "79.00"} ``` ```http HTTP/1.1 204 No Content Cache-Group-Invalidation: "product-8812", "category-shoes" ``` --- # Cache-Groups header > Tags a cacheable response with one or more group names, so a cache can invalidate every stored response in a group together. Source: https://apiguide.dev/headers/cache-groups Direction: response Standardized: yes Defined in: RFC 9875 Updated: 2026-10-17 ## What is the Cache-Groups header? The `Cache-Groups` response header, defined in Section 2 of [RFC 9875](https://www.rfc-editor.org/rfc/rfc9875.html) (HTTP Cache Groups, Standards Track, October 2025), associates a stored response with one or more named groups. HTTP caching otherwise works one resource at a time; groups let a cache treat related responses together, most usefully by invalidating them together. The value is a [Structured Field](/specifications/structured-fields) List of Strings. Each String names a group. The names are opaque to the cache: they may mean something to your server, but the cache only compares them, character by character and case-sensitively. Order does not matter, and unrecognized parameters are ignored. ```http Cache-Groups: "scripts" ``` Two stored responses are in the same group when both carry the same String in `Cache-Groups` and both come from the same origin. Groups never cross origins, and they work within a single cache; RFC 9875 does not address keeping several caches in sync. When a cache invalidates a stored response, it MAY also invalidate every other stored response that shares a group with it. That grouped invalidation does not cascade further. A response can also trigger it directly with [`Cache-Group-Invalidation`](/headers/cache-group-invalidation). ## API Usage & Best Practices * **Group by what changes together.** Tag every representation that depends on a piece of data with a name for that data: a collection, a tenant, a product. Then a write to that data can invalidate all of them, which is the problem URL-prefix purges solve badly. See [cache invalidation](/guides/cache-invalidation). * **Keep names short and few.** Implementations MUST support at least 32 groups per field, each at least 32 characters long. Stay inside that and your groups work everywhere that implements the RFC. * **Remember the MAY.** RFC 9875 only permits caches to invalidate grouped responses. A cache that ignores `Cache-Groups` is still conforming. Keep freshness lifetimes in [`Cache-Control`](/headers/cache-control) honest rather than relying on group invalidation to save you from stale data. * **Check your CDN's own tagging.** Many CDNs already offer tag-based purging through vendor-specific headers and purge APIs. Whether a given cache honors `Cache-Groups` is something to confirm in its documentation, not assume. * **Watch out on shared hosting.** Every resource on an origin can join any group on that origin. If several parties share one origin, one of them can group its resources with another's and invalidate them. Control who can set these headers. ## Examples A script tagged with one group, from RFC 9875: ```http HTTP/1.1 200 OK Content-Type: application/javascript Cache-Control: max-age=3600 Cache-Groups: "scripts" ``` An API representation that depends on a product and on its category: ```http HTTP/1.1 200 OK Content-Type: application/json Cache-Control: public, max-age=300 Cache-Groups: "product-8812", "category-shoes" ``` --- # Cache-Status header > Reports how each cache on the path handled a response: hit or forwarded, why, and how much freshness remains. Source: https://apiguide.dev/headers/cache-status Direction: response Standardized: yes Defined in: RFC 9211 Updated: 2026-10-14 ## What is the Cache-Status header? The `Cache-Status` response header, defined in [RFC 9211](https://www.rfc-editor.org/rfc/rfc9211.html), is the standard way for a cache to say what it did with a request. It replaces the vendor-specific `X-Cache` and `X-Cache-Hit` style headers with one format every cache can share. It is a [Structured Field](/specifications/structured-fields) List. Each member names one cache, as a token or string, followed by parameters. The first member is the cache **closest to the origin** and the last is the one closest to the client, and each cache appends its entry while preserving those already present. | Parameter | Type | Meaning | | :--- | :--- | :--- | | `hit` | Boolean | Served from cache without going forward. Mutually exclusive with `fwd` | | `fwd` | Token | The request went forward toward the origin, and why | | `fwd-status` | Integer | The status the next hop returned; if absent, assume the status in this response | | `ttl` | Integer | Remaining freshness in seconds; negative means stale | | `stored` | Boolean | Whether the cache stored the forwarded response | | `collapsed` | Boolean | Whether the request was collapsed with others in flight | | `key` | String | A representation of the cache key, implementation-specific | | `detail` | String or Token | Implementation-specific extra information | The `fwd` values, most specific first: `bypass` (configured not to cache), `method` (the method requires forwarding), `uri-miss` (nothing stored for this URI), `vary-miss` (stored responses exist but none match [`Vary`](/headers/vary)), `miss` (the cache cannot tell which of the two), `request` (the request's [`Cache-Control`](/headers/cache-control) forbade using a fresh response), `stale` (the selected response was stale) and `partial` (a stored partial response did not cover the requested range). ## API Usage & Best Practices * **Read it before guessing.** When a client reports stale data, `Cache-Status` tells you which layer served it and with how much `ttl` left. Combined with [`Age`](/headers/age), it settles most caching arguments in one request. * **Distinguish `vary-miss` from `uri-miss`.** A high rate of `vary-miss` means the URI is cached but your `Vary` is fragmenting the cache, often because it includes a header with high cardinality. That is a fix in the API, not in the CDN. * **Use `fwd=stale; fwd-status=304` to confirm revalidation works.** It means the cache had a stale copy, sent a conditional request, and the origin answered [`304 Not Modified`](/status-codes/304). If you only ever see `fwd-status=200`, your validators are not being honored. * **Name your own caches clearly.** If you run an application-level or gateway cache, emit `Cache-Status` with a stable identifier for it, not a hostname. Append to the existing value rather than replacing it. * **Do not expose `key` or `detail` to the public.** The RFC's security considerations note that cache keys help an attacker understand and target cache poisoning, and that knowing whether a response was stored can support timing attacks. Send the sensitive parameters only to authorized clients, or strip them at the edge. * **Do not build client behavior on it.** It is a diagnostic field. Clients should use [`Cache-Control`](/headers/cache-control), [`ETag`](/headers/etag) and [`Age`](/headers/age) for freshness decisions, not whether some cache reported a hit. ## Examples A CDN hit with nine minutes of freshness left, in front of an origin cache that also hit: ```http HTTP/1.1 200 OK Content-Type: application/json Age: 42 Cache-Status: OriginCache; hit; ttl=1100, "ExampleCDN"; hit; ttl=545 ``` A stale entry revalidated against the origin, which confirmed it was unchanged: ```http HTTP/1.1 200 OK Content-Type: application/json Cache-Status: ExampleCDN; fwd=stale; fwd-status=304 ``` A request for a URI with no stored response, collapsed with concurrent requests and stored for later: ```http HTTP/1.1 200 OK Content-Type: application/json Cache-Status: ExampleCDN; fwd=uri-miss; collapsed; stored ``` --- # CDN-Cache-Control header > Cache directives aimed only at CDN caches, letting an origin set edge caching separately from browsers and other caches. Source: https://apiguide.dev/headers/cdn-cache-control Direction: response Standardized: yes Defined in: RFC 9213 Updated: 2026-10-14 ## What is the CDN-Cache-Control header? The `CDN-Cache-Control` response header, defined in [RFC 9213](https://www.rfc-editor.org/rfc/rfc9213.html), carries the same directives as [`Cache-Control`](/headers/cache-control) but applies only to CDN caches: caches in a distributed network acting on behalf of the origin. It lets an origin tell the edge one thing and browsers and other caches another, without the overloading that `s-maxage` does across every shared cache. RFC 9213 calls this a *targeted cache-control field*. A cache that supports one keeps an ordered target list of field names. For each response, it uses the first field on that list with a valid, non-empty value, and when it does, it **ignores `Cache-Control` and `Expires` entirely** for that response. If none is valid, normal HTTP caching applies. Caches not targeted by the field must ignore it and pass it through. Unlike `Cache-Control`, it is a [Structured Field](/specifications/structured-fields) Dictionary. Directives such as `max-age=600` and `no-store` look the same, but a value that fails to parse makes the cache ignore the whole field, as though it were absent. ## API Usage & Best Practices * **Cache at the edge, not in the browser.** The commonest use: let the CDN hold a response for minutes while clients revalidate on every request. `CDN-Cache-Control: max-age=600` with `Cache-Control: no-cache` does exactly that. * **Keep a sensible `Cache-Control` alongside it.** Caches that do not understand `CDN-Cache-Control` fall back to `Cache-Control`. Never send only the targeted field and assume nothing else will cache the response. * **Purge when you lengthen edge TTLs.** A long CDN freshness lifetime means updates do not reach clients until the CDN entry expires or is purged. See [CDN and edge caching](/guides/cdn-edge-caching) and [cache invalidation](/guides/cache-invalidation). * **Watch the `Age` it produces.** A CDN holding a response longer than `Cache-Control: max-age` allows will forward it with an [`Age`](/headers/age) that already exceeds `max-age`, so downstream caches treat it as stale immediately. RFC 9213 lets implementations mitigate this by removing `Age` or updating [`Date`](/headers/date), but does not require it. Check what your CDN does. * **To keep responses out of every cache except the CDN,** send `Cache-Control: no-store` with a non-empty `CDN-Cache-Control`. RFC 9213's own example uses `CDN-Cache-Control: none`, which is not a registered directive but stops the field being empty, so the CDN obeys it instead of `no-store` and falls back on its own defaults. * **Never use it for personalized responses.** Responses that depend on [`Authorization`](/headers/authorization) or a cookie must not be cached at the edge unless the cache key includes the identity. `private` in `CDN-Cache-Control` is honored, but the safer default is not to send an edge-cacheable directive at all on authenticated endpoints. * **Know your CDN's own field.** RFC 9213 expects CDNs to define their own more specific fields that sit ahead of `CDN-Cache-Control` on the target list. Cloudflare, for example, supports both `CDN-Cache-Control`, which it obeys and passes downstream to other CDNs, and `Cloudflare-CDN-Cache-Control`, which only Cloudflare obeys and which it does not forward. When both are present, Cloudflare uses the more specific one. Check your provider's documentation rather than assuming. ## Examples Edge caching for ten minutes, with browsers revalidating every time: ```http HTTP/1.1 200 OK Content-Type: application/json ETag: "v42" Cache-Control: no-cache CDN-Cache-Control: max-age=600 ``` A CDN-specific lifetime with a general fallback for other shared caches, taken from RFC 9213: ```http HTTP/1.1 200 OK Content-Type: application/json Cache-Control: max-age=60, s-maxage=120 CDN-Cache-Control: max-age=600 ``` Stored by CDN caches for ten minutes, and by no other cache: ```http HTTP/1.1 200 OK Content-Type: application/json Cache-Control: no-store CDN-Cache-Control: max-age=600 ``` --- # Client-Cert header > Lets a TLS-terminating reverse proxy pass the client's mTLS certificate to the origin, as a base64 DER byte sequence. Source: https://apiguide.dev/headers/client-cert Direction: request Standardized: yes Defined in: RFC 9440, Section 2 Updated: 2026-10-17 ## What is the Client-Cert header? The `Client-Cert` request header, defined in Section 2.2 of [RFC 9440](https://www.rfc-editor.org/rfc/rfc9440.html), carries the end-entity certificate a client presented in a [mutual TLS](/guides/mutual-tls) handshake, from the TLS-terminating reverse proxy that validated it to the backend origin server. RFC 9440 was published in July 2023 as an Informational RFC, not on the Standards Track; it documents a common deployment pattern and gives it one interoperable header in place of the many vendor-specific ones. The value is a [Structured Field](/specifications/structured-fields) Byte Sequence: the certificate's DER encoding, base64 without line breaks, between colons. A PEM certificate converts by replacing the `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----` lines with `:` and removing the line breaks. It is only for requests and MUST NOT be used in responses. It is a singleton: one certificate, one header line. The rest of the chain, if the proxy is configured to send it, goes in [`Client-Cert-Chain`](/headers/client-cert-chain). ## API Usage & Best Practices * **Strip it at the edge, every time.** The proxy MUST remove or overwrite any `Client-Cert` the client sent, and MUST remove it entirely on connections where no client certificate was negotiated. RFC 9440 points out that forgetting this does not fail safe: everything still works, and any client can now claim any certificate. * **Only trust it from your proxy.** The backend MUST accept it only from a trusted proxy, over a connection that is authenticated or on a network the client cannot reach. If clients can connect to the origin directly, the header is worthless. Firewall the origin first. * **Let the proxy validate; let the app decide.** The proxy checks the certificate against its trust store during the handshake. The application reads `Client-Cert` to identify the caller and authorizes with [`403 Forbidden`](/status-codes/403) when the certificate is not acceptable for the request. Clients that expect a TLS alert for a rejected certificate will not get one this way. * **Vary or do not cache.** A response selected by the certificate MUST be uncacheable, for example `Cache-Control: no-store`, or carry [`Vary`](/headers/vary)`: Client-Cert`. The client never sees `Client-Cert`, so a proxy that finds it in `Vary` SHOULD rewrite `Vary` to `*` before passing the response on, which stops the user agent caching it. * **Raise header size limits.** Certificates are large. Origins may need a bigger maximum header size, and RFC 9440 mentions [`431 Request Header Fields Too Large`](/status-codes/431) as what an origin sends when it is exceeded. * **Make it opt-in on both sides.** Producing and consuming the header SHOULD be configuration options that are off by default. * **Prefer it to ad hoc headers.** Proxies have long used their own names for this, and some pass only the subject or a hash. Those are not interoperable, and a subject string is not the certificate. `Client-Cert` gives the backend the whole certificate in a defined encoding. * **Clients never send it.** RFC 9440 says clients MUST NOT use it, and forward proxies MUST NOT add or modify it. A request arriving at your edge with `Client-Cert` already set MAY be rejected with [`400 Bad Request`](/status-codes/400). ## Examples The request the proxy forwards to the origin, from RFC 9440 Appendix A (on one line here; the RFC folds it for display): ```http GET /v1/accounts/acc_17 HTTP/1.1 Host: backend.internal.example Client-Cert: :MIIBqDCCAU6gAwIBAgIBBzAKBggqhkjOPQQDAjA6MRswGQYDVQQKDBJMZXQncyBBdXRoZW50aWNhdGUxGzAZBgNVBAMMEkxBIEludGVybWVkaWF0ZSBDQTAeFw0yMDAxMTQyMjU1MzNaFw0yMTAxMjMyMjU1MzNaMA0xCzAJBgNVBAMMAkJDMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE8YnXXfaUgmnMtOXU/IncWalRhebrXmckC8vdgJ1p5Be5F/3YC8OthxM4+k1M6aEAEFcGzkJiNy6J84y7uzo9M6NyMHAwCQYDVR0TBAIwADAfBgNVHSMEGDAWgBRm3WjLa38lbEYCuiCPct0ZaSED2DAOBgNVHQ8BAf8EBAMCBsAwEwYDVR0lBAwwCgYIKwYBBQUHAwIwHQYDVR0RAQH/BBMwEYEPYmRjQGV4YW1wbGUuY29tMAoGCCqGSM49BAMCA0gAMEUCIBHda/r1vaL6G3VliL4/Di6YK0Q6bMjeSkC3dFCOOB8TAiEAx/kHSB4urmiZ0NX5r5XarmPk0wmuydBVoU4hBVZ1yhk=: ``` A response whose content depends on the certificate: ```http HTTP/1.1 200 OK Content-Type: application/json Cache-Control: private, max-age=60 Vary: Client-Cert ``` --- # Client-Cert-Chain header > Carries the intermediate certificates behind a client's mTLS certificate from a TLS-terminating proxy to the origin, as a list of byte sequences. Source: https://apiguide.dev/headers/client-cert-chain Direction: request Standardized: yes Defined in: RFC 9440, Section 2 Updated: 2026-10-17 ## What is the Client-Cert-Chain header? The `Client-Cert-Chain` request header, defined in Section 2.3 of [RFC 9440](https://www.rfc-editor.org/rfc/rfc9440.html) (Informational, July 2023), lets a TLS-terminating reverse proxy pass the certificate chain a client used in a [mutual TLS](/guides/mutual-tls) handshake to the backend origin. It accompanies [`Client-Cert`](/headers/client-cert), which carries the end-entity certificate. The value is a [Structured Field](/specifications/structured-fields) List of Byte Sequences, each one a base64 DER-encoded X.509 certificate between colons, in the same order as in the TLS handshake. It does not repeat the end-entity certificate already in `Client-Cert`, and it MUST NOT appear unless `Client-Cert` is also present. The root certificate MAY be left out when the origin is known to have that trust anchor. Sending it is optional for the proxy, and it is only for requests. Unlike `Client-Cert`, it can be split across several header lines, which can help header compression. ## API Usage & Best Practices * **Send it only if the origin needs it.** Most backends only need the client certificate to identify the caller, because the proxy has already validated the chain. Forward the chain when the application has to inspect an intermediate, for example to tell which issuing CA or tenant a certificate belongs to. * **Leave out the root.** The origin already trusts it, and every certificate adds a large value to every request. * **Sanitize it exactly like `Client-Cert`.** The proxy MUST remove or overwrite any copy the client sent, and remove it on connections without a client certificate. The backend MUST only accept it from a trusted proxy. An incoming request that already has it MAY be rejected with [`400 Bad Request`](/status-codes/400). * **Budget for size.** A chain can be several kilobytes. Raise the origin's header limits, or expect [`431 Request Header Fields Too Large`](/status-codes/431). Over HTTP/2 or HTTP/3 to the origin, varying certificate values from many clients can also hurt HPACK or QPACK compression; RFC 9440 suggests a larger dynamic table or sending the value as a literal. * **Keep session resumption consistent.** Some TLS stacks do not keep client certificate information across resumption. RFC 9440 says to disable resumption for client-certificate connections, or omit the fields from the start, rather than send them inconsistently. * **Do not re-validate the chain at the origin as if it came from the client.** It came from your proxy, which already validated it. Re-validating against a different trust store only creates disagreements between the two. ## Examples The proxy forwarding both the client certificate and its chain (here the intermediate and, as in RFC 9440 Appendix A, the root; many deployments omit the root). The two chain certificates are sent as separate field lines, which is equivalent to one comma-separated list: ```http GET /v1/accounts/acc_17 HTTP/1.1 Host: backend.internal.example Client-Cert: :MIIBqDCCAU6gAwIBAgIBBzAKBggqhkjOPQQDAjA6MRswGQYDVQQKDBJMZXQncyBBdXRoZW50aWNhdGUxGzAZBgNVBAMMEkxBIEludGVybWVkaWF0ZSBDQTAeFw0yMDAxMTQyMjU1MzNaFw0yMTAxMjMyMjU1MzNaMA0xCzAJBgNVBAMMAkJDMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE8YnXXfaUgmnMtOXU/IncWalRhebrXmckC8vdgJ1p5Be5F/3YC8OthxM4+k1M6aEAEFcGzkJiNy6J84y7uzo9M6NyMHAwCQYDVR0TBAIwADAfBgNVHSMEGDAWgBRm3WjLa38lbEYCuiCPct0ZaSED2DAOBgNVHQ8BAf8EBAMCBsAwEwYDVR0lBAwwCgYIKwYBBQUHAwIwHQYDVR0RAQH/BBMwEYEPYmRjQGV4YW1wbGUuY29tMAoGCCqGSM49BAMCA0gAMEUCIBHda/r1vaL6G3VliL4/Di6YK0Q6bMjeSkC3dFCOOB8TAiEAx/kHSB4urmiZ0NX5r5XarmPk0wmuydBVoU4hBVZ1yhk=: Client-Cert-Chain: :MIIB5jCCAYugAwIBAgIBFjAKBggqhkjOPQQDAjBWMQswCQYDVQQGEwJVUzEbMBkGA1UECgwSTGV0J3MgQXV0aGVudGljYXRlMSowKAYDVQQDDCFMZXQncyBBdXRoZW50aWNhdGUgUm9vdCBBdXRob3JpdHkwHhcNMjAwMTE0MjEzMjMwWhcNMzAwMTExMjEzMjMwWjA6MRswGQYDVQQKDBJMZXQncyBBdXRoZW50aWNhdGUxGzAZBgNVBAMMEkxBIEludGVybWVkaWF0ZSBDQTBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABJf+aA54RC5pyLAR5yfXVYmNpgd+CGUTDp2KOGhc0gK91zxhHesEYkdXkpS2UN8Kati+yHtWCV3kkhCngGyv7RqjZjBkMB0GA1UdDgQWBBRm3WjLa38lbEYCuiCPct0ZaSED2DAfBgNVHSMEGDAWgBTEA2Q6eecKu9g9yb5glbkhhVINGDASBgNVHRMBAf8ECDAGAQH/AgEAMA4GA1UdDwEB/wQEAwIBhjAKBggqhkjOPQQDAgNJADBGAiEA5pLvaFwRRkxomIAtDIwg9D7gC1xzxBl4r28EzmSO1pcCIQCJUShpSXO9HDIQMUgH69fNDEMHXD3RRX5gP7kuu2KGMg==: Client-Cert-Chain: :MIICBjCCAaygAwIBAgIJAKS0yiqKtlhoMAoGCCqGSM49BAMCMFYxCzAJBgNVBAYTAlVTMRswGQYDVQQKDBJMZXQncyBBdXRoZW50aWNhdGUxKjAoBgNVBAMMIUxldCdzIEF1dGhlbnRpY2F0ZSBSb290IEF1dGhvcml0eTAeFw0yMDAxMTQyMTI1NDVaFw00MDAxMDkyMTI1NDVaMFYxCzAJBgNVBAYTAlVTMRswGQYDVQQKDBJMZXQncyBBdXRoZW50aWNhdGUxKjAoBgNVBAMMIUxldCdzIEF1dGhlbnRpY2F0ZSBSb290IEF1dGhvcml0eTBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABFoaHU+Z5bPKmGzlYXtCf+E6HYj62fORaHDOrt+yyh3H/rTcs7ynFfGn+gyFsrSP3Ez88rajv+U2NfD0o0uZ4PmjYzBhMB0GA1UdDgQWBBTEA2Q6eecKu9g9yb5glbkhhVINGDAfBgNVHSMEGDAWgBTEA2Q6eecKu9g9yb5glbkhhVINGDAPBgNVHRMBAf8EBTADAQH/MA4GA1UdDwEB/wQEAwIBhjAKBggqhkjOPQQDAgNIADBFAiEAmAeg1ycKHriqHnaD4M/UDBpQRpkmdcRFYGMg1Qyrkx4CIB4ivz3wQcQkGhcsUZ1SOImd/lq1Q0FLf09rGfLQPWDc: ``` --- # Connection header > Lists control options for the current HTTP/1.1 connection and names the hop-by-hop fields that intermediaries must strip before forwarding. Source: https://apiguide.dev/headers/connection Direction: both Standardized: yes Defined in: RFC 9110, Section 7.6.1 Updated: 2026-10-14 ## What is the Connection header? The `Connection` header, defined in RFC 9110 Section 7.6.1, carries control options for the current connection only. Each option is a token, such as `close`, `keep-alive` or `upgrade`, and any option that matches a header name marks that header as hop-by-hop: meant for the immediate recipient, not for every hop on the chain. An intermediary MUST parse `Connection` before forwarding, remove every field it names, and then remove or replace `Connection` itself. It is an HTTP/1.x mechanism. HTTP/2 and HTTP/3 carry connection metadata in their own framing; RFC 9113 Section 8.2.2 and RFC 9114 Section 4.2 forbid `Connection` and the fields it governs (`Keep-Alive`, `Proxy-Connection`, [`Transfer-Encoding`](/headers/transfer-encoding) and [`Upgrade`](/headers/upgrade)), and any message containing them MUST be treated as malformed. ## API Usage & Best Practices * **Strip hop-by-hop fields in any proxy you write**: A gateway or reverse proxy that copies request headers to the upstream verbatim forwards fields that were never meant for it. Remove `Connection`, every field it lists, and the known hop-by-hop fields (`Keep-Alive`, `Proxy-Connection`, `TE`, `Transfer-Encoding`, `Upgrade`) whether or not they are listed. Translating to HTTP/2 without doing this produces malformed messages that the next hop will reject. * **Assume clients will abuse the list**: A client controls `Connection`, so it can name any header and have conforming proxies delete it in transit. RFC 9110 says a sender MUST NOT list a field intended for all recipients, such as [`Cache-Control`](/headers/cache-control), but nothing stops an attacker doing so. Add the headers your edge injects for the back end (an authenticated-user header, [`X-Forwarded-For`](/headers/x-forwarded-for)) after hop-by-hop stripping, never before, and have the back end treat their absence as a failure rather than as "no restriction". * **Use `close` to end the connection cleanly**: `Connection: close` tells the peer the connection will not be reused after this response. Send it when draining a server for shutdown rather than resetting connections mid-request. * **Do not set it by hand in HTTP/2 or HTTP/3 code**: Frameworks that serve multiple protocols will drop or reject it. Persistence is the default in HTTP/1.1 anyway, so `Connection: keep-alive` is redundant there. * **List the options that need it**: A sender of `Upgrade` or `TE` MUST also list `upgrade` or `TE` in `Connection`. ## Examples A WebSocket handshake marks `Upgrade` as hop-by-hop: ```http GET /v1/stream HTTP/1.1 Host: api.example.com Connection: Upgrade Upgrade: websocket ``` A server signaling that it will close the connection after this response: ```http HTTP/1.1 503 Service Unavailable Connection: close Retry-After: 30 Content-Type: application/problem+json ``` --- # Content-Digest header > Carries a hash of the actual message content, so the recipient can check the bytes arrived intact. Source: https://apiguide.dev/headers/content-digest Direction: both Standardized: yes Defined in: RFC 9530, Section 2 Updated: 2026-10-17 ## What is the Content-Digest header? The `Content-Digest` field, defined in RFC 9530 Section 2, carries one or more digests of the message content: the bytes of the body as actually sent, after any [`Content-Encoding`](/headers/content-encoding) has been applied and limited to the range in a [`206 Partial Content`](/status-codes/206) response. It can be sent on requests and responses, and in a trailer section. The value is a [Structured Field](/specifications/structured-fields) Dictionary. Each key is a hash algorithm from the IANA "Hash Algorithms for HTTP Digest Fields" registry, and each value is the digest as a byte sequence, base64 between colons. `sha-256` and `sha-512` are the registry's "Active" algorithms; `md5`, `sha` (SHA-1), `unixsum`, `unixcksum`, `adler` and `crc32c` are "Deprecated". RFC 9530 obsoletes RFC 3230, and with it the old `Digest` and `Want-Digest` fields. Do not emit those in new work. `Digest` was meant to hash the representation, but implementations disagreed about whether that meant the content, which is why the replacement splits the job into `Content-Digest` and [`Repr-Digest`](/headers/repr-digest). See [Digest Fields](/specifications/digest-fields) for the full specification. ## API Usage & Best Practices * **Content or representation?** Use `Content-Digest` when you want to verify the exact bytes in this message, for example a webhook body or a signed request. Use `Repr-Digest` when you care about the resource's full representation independent of ranges, such as checking a reassembled download. * **Use sha-256 or sha-512**: The deprecated algorithms must not be used where an attacker could be involved, such as a digest that is covered by a signature. They are only there for migrating stored RFC 3230 checksums. * **A digest alone is not authentication**: Anyone who can change the body can recompute the digest. To prove who sent the content, cover `Content-Digest` with [HTTP Message Signatures](/specifications/http-message-signatures) (see [`Signature`](/headers/signature)). Signing the digest is how a signature protects the body. * **Compute it after encoding**: Because it covers the bytes on the wire, a gzip-encoded body and its uncompressed form have different `Content-Digest` values. Compute it on the final bytes, after compression. * **Ask for it with Want-Content-Digest**: A client sends [`Want-Content-Digest`](/headers/want-content-digest) to request a content digest, and a server sends it in a response to ask clients to include one on future requests. It is a Dictionary of algorithm to preference, 1 (least preferred) to 10 (most preferred), with 0 meaning "not acceptable". It is only a hint; the recipient may ignore it. * **Reject mismatches**: If a digest you require does not match, refuse the request with [`400 Bad Request`](/status-codes/400) rather than processing a body you cannot trust. ## Examples A request carrying a digest of its body: ```http POST /v1/orders HTTP/1.1 Host: api.example.com Content-Type: application/json Content-Length: 35 Content-Digest: sha-256=:kS5noiNBB8bB3tb+nPoVeQlO6I16ckYSFzTQ91VVpZM=: {"id":"ord_123","status":"shipped"} ``` A client asking for SHA-512 if possible, SHA-256 otherwise, and never the Unix `sum` checksum: ```http GET /v1/exports/exp_9f2/download HTTP/1.1 Host: api.example.com Want-Content-Digest: sha-512=10, sha-256=3, unixsum=0 ``` --- # Content-Disposition header > Indicates whether the body should be displayed inline or treated as a downloadable attachment. Source: https://apiguide.dev/headers/content-disposition Direction: response Standardized: yes Defined in: RFC 6266 Updated: 2026-07-10 ## What is the Content-Disposition header? The `Content-Disposition` response header tells the client how to present the body: rendered `inline` within the browser, or as an `attachment` that prompts a download. When set to `attachment`, it can also suggest a filename. ## API Usage & Best Practices * **Trigger downloads**: Use `attachment; filename="report.csv"` when an API endpoint returns a file the user should save rather than view. * **Display inline**: Use `inline` for previewable content such as PDFs or images meant to render directly. * **Encode non-ASCII names**: Use the `filename*` parameter with UTF-8 encoding (RFC 5987) for filenames containing non-ASCII characters. ## Examples ```http HTTP/1.1 200 OK Content-Type: text/csv Content-Disposition: attachment; filename="export.csv" ``` --- # Content-Encoding header > Indicates the compression encoding that has been applied to the message body. Source: https://apiguide.dev/headers/content-encoding Direction: both Standardized: yes Defined in: RFC 9110, Section 8.4 Updated: 2026-07-10 ## What is the Content-Encoding header? The `Content-Encoding` header lists any compression that has been applied to the representation body, so the recipient knows which transformation to reverse before decoding. Common values are `gzip`, `br` (Brotli), `zstd`, and `deflate`. ## API Usage & Best Practices * **Pair with `Accept-Encoding`**: A server should only apply an encoding that the client advertised as acceptable in its `Accept-Encoding` request header. * **Reduce payload size**: Compressing JSON responses with `gzip` or `br` can dramatically cut bandwidth for API responses. * **Order matters**: When multiple encodings are applied, list them in the order they were applied so the client can reverse them correctly. ## Examples ```http HTTP/1.1 200 OK Content-Type: application/json Content-Encoding: gzip ``` --- # Content-Language header > Describes the natural language(s) of the intended audience for the message body. Source: https://apiguide.dev/headers/content-language Direction: both Standardized: yes Defined in: RFC 9110, Section 8.5 Updated: 2026-07-10 ## What is the Content-Language header? The `Content-Language` header states the natural language(s) that the representation body is intended for, using language tags such as `en`, `en-US`, or `fr-CA`. It describes the audience, not necessarily every language present in the content. ## API Usage & Best Practices * **Pair with `Accept-Language`**: Use it to confirm which language variant was returned in response to a client's `Accept-Language` preferences. * **Support content negotiation**: Set it on localized API responses so clients and caches can distinguish between language variants of the same resource. * **Multiple tags allowed**: A comma-separated list can indicate content intended for several audiences at once. ## Examples ```http HTTP/1.1 200 OK Content-Type: application/json Content-Language: en-US ``` --- # Content-Length header > Indicates the size of the request or response body in bytes. Source: https://apiguide.dev/headers/content-length Direction: both Standardized: yes Defined in: RFC 9110, Section 8.6 Updated: 2026-10-14 ## What is the Content-Length header? The `Content-Length` header indicates the size of the payload body in decimal number of octets (bytes) sent to the recipient. ## API Usage & Best Practices * **Validate request sizing**: Gateways check this header to immediately reject payloads exceeding limits with a `413 Content Too Large`. * **Reject missing lengths only if you must**: RFC 9112 lets a server answer a request that has a body but no `Content-Length` with `411 Length Required`, but every HTTP/1.1 recipient must be able to parse chunked bodies, so reserve 411 for a server that genuinely cannot accept a body of unknown length, such as one that has to enforce a size limit before reading. An explicit `Content-Length: 0` is a valid, empty body rather than a missing header, and shouldn't trigger 411. ## Examples ```http POST /v1/leads HTTP/1.1 Content-Type: application/json Content-Length: 124 ``` --- # Content-Location header > Identifies a URI for the specific representation enclosed in the message, distinct from the redirect or creation target given by Location. Source: https://apiguide.dev/headers/content-location Direction: both Standardized: yes Defined in: RFC 9110, Section 8.7 Updated: 2026-10-14 ## What is the Content-Location header? The `Content-Location` header, defined in Section 8.7 of [RFC 9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-content-location), gives a URI for the representation enclosed in the message. The test the RFC uses is concrete: a `GET` on that URI, at the time the message was generated, would return a `200 OK` with the same representation as this message's content. It is representation metadata. It does not redirect anything, it does not replace the request's target URI, and a client is never expected to follow it. That is the key difference from [`Location`](/headers/location). `Location` points to a resource **related to the response**, with the relationship set by the status code: the resource created by a [`201 Created`](/status-codes/201), or the target to redirect to on a `3xx`. `Content-Location` describes **the body you are holding**. The two can appear in the same response. | Response | `Content-Location` means | | :--- | :--- | | `2xx` to `GET`, same URI as the target | Nothing beyond the default; the body is the target's representation | | `2xx` to `GET`, different URI | The target is negotiated, and this is the URI of the specific variant selected | | `2xx` to `PUT` or `POST`, same URI as the target | The body is the new state of the resource, not a status message | | `201`, same URI as `Location` | The body is a current representation of the newly created resource | | Any other `2xx` to a state-changing request | The body is a report on the action, retrievable later at that URI | ## API Usage & Best Practices * **Send it with `Location` on a `201` that returns the resource.** When `POST` creates a resource and the response body is that resource, set `Content-Location` to the same URI as `Location`. That tells the client it already has the current representation and does not need a follow-up [`GET`](/methods/get). * **Use it to say a `PUT` or `PATCH` response is the resource.** A `200` to a [`PUT`](/methods/put) carrying `Content-Location` equal to the target URI tells the client the body is the updated state, so it can replace its local copy. Without it, the body could just as well be a summary of what happened. * **Use it to give a receipt a permanent address.** When a `POST` to `/v1/payments` returns a payment report, a `Content-Location` of `/v1/payments/pay_123/receipt` says the same report can be fetched there later. * **Use it for negotiated variants.** If `/v1/reports/42` serves JSON or CSV depending on [`Accept`](/headers/accept), the CSV response can carry `Content-Location: /v1/reports/42.csv` to name the specific variant. Pair that with [`Vary`](/headers/vary) so caches key correctly. * **Never use it in place of `Location`.** Clients do not redirect on `Content-Location`, and a `201` without `Location` is missing the one field that says where the new resource is. * **Do not treat a different URI as authoritative.** RFC 9110 notes that a `Content-Location` pointing somewhere else can only be trusted if both URIs share the same owner, which HTTP cannot prove. A client should not, for example, cache a representation under a third-party URI because a response claimed it. * **On requests, treat it as context only.** A client may send `Content-Location` to say where it originally got the content it is sending. The server must not save it verbatim as part of the representation and must not let it change the request's meaning: a `PUT` to a negotiated resource updates that resource, not the variant named in `Content-Location`. ## Examples A `201` whose body is the created resource: ```http HTTP/1.1 201 Created Location: https://api.example.com/v1/orders/ord_123 Content-Location: https://api.example.com/v1/orders/ord_123 Content-Type: application/json {"id": "ord_123", "status": "pending", "total": "49.00"} ``` A negotiated response naming the variant it selected: ```http HTTP/1.1 200 OK Content-Type: text/csv Content-Location: /v1/reports/42.csv Vary: Accept ``` A `POST` that returns a receipt also available at its own URI: ```http HTTP/1.1 200 OK Content-Type: application/json Content-Location: /v1/payments/pay_123/receipt ``` --- # Content-Range header > Indicates which portion of a resource is delivered in a partial response. Source: https://apiguide.dev/headers/content-range Direction: response Standardized: yes Defined in: RFC 9110, Section 14.4 Updated: 2026-10-14 ## What is the Content-Range header? The `Content-Range` response header describes where a returned chunk of data fits within the complete resource. It accompanies a `206 Partial Content` response and states the byte range being sent along with the total size of the full representation. ## API Usage & Best Practices * **Reassembling downloads**: Clients use the range and total-length values to place each chunk correctly and to know when the whole resource has been received. * **Signaling unsatisfiable ranges**: In a `416 Range Not Satisfiable` response, `Content-Range: bytes */146515` reports the total size so the client can retry with a valid range. ## Examples ```http HTTP/1.1 206 Partial Content Content-Range: bytes 0-1023/146515 Content-Length: 1024 ``` --- # Content-Security-Policy header > Tells browsers which sources a document may load and who may frame it. For a JSON API, send the most restrictive policy there is. Source: https://apiguide.dev/headers/content-security-policy Direction: response Standardized: yes Defined in: W3C Content Security Policy Level 3 Updated: 2026-10-17 ## What is the Content-Security-Policy header? The `Content-Security-Policy` (CSP) response header declares a policy that the browser enforces on the document or worker created from the response: which origins scripts, styles, images and connections may come from, whether inline script may run, where forms may submit and which pages may embed it in a frame. It is defined in the W3C [Content Security Policy Level 3](https://www.w3.org/TR/CSP3/) specification, still a Working Draft, and is registered as a permanent field in the IANA HTTP Field Name Registry. A policy is a semicolon-separated list of directives, each a name followed by a source list. The ones that matter for an API: | Directive | Effect | | :--- | :--- | | `default-src` | The fallback for every fetch directive (`script-src`, `style-src`, `img-src`, `connect-src` and so on) that is not set explicitly. `'none'` means nothing may be loaded. | | `frame-ancestors` | Which origins may embed the response in a frame. `'none'` forbids all framing. It does **not** fall back to `default-src`. | | `sandbox` | Applies iframe-style sandbox restrictions to the document, blocking script, forms and more. | | `report-to` | Where to send violation reports. Replaces the deprecated `report-uri`. | Browsers ignore CSP for non-document requests: a `fetch()` from your single-page app is governed by [CORS](/guides/cors), not by the CSP on the API response. The policy only takes effect when a browser renders the response itself, for example when a user opens an API URL directly, a response is loaded in a frame, or an attacker tricks a browser into treating your response as HTML. ## API Usage & Best Practices * **For JSON APIs, send the restrictive policy.** `Content-Security-Policy: default-src 'none'; frame-ancestors 'none'` costs one constant header and has nothing to break: a JSON response loads no scripts, styles or images, and nobody legitimately frames it. Set it once at the gateway or framework level for every API response, including errors. * **Include `frame-ancestors` explicitly.** CSP Level 3 spells this out: a policy of `default-src 'none'` "will still allow the resource to be embedded by anyone." `frame-ancestors 'none'` is what blocks clickjacking-style framing of your responses, and it supersedes [`X-Frame-Options`](/headers/x-frame-options) in browsers that support both. * **Know where it actually helps.** The real protection is for the response that ends up rendered as HTML: an error page from your framework that reflects a path or parameter, a misconfigured route that returns `text/html`, a user-uploaded file served back. `default-src 'none'` stops script on such a page from running inline or loading anything, which turns a reflected XSS into a dead end. Pair it with a correct [`Content-Type`](/headers/content-type) and [`X-Content-Type-Options: nosniff`](/headers/x-content-type-options). * **It does nothing for machine clients.** SDKs, `curl` and server-to-server callers ignore it completely. That is not a reason to omit it; it is a reason not to count it as access control. * **APIs that serve HTML need a real policy.** OAuth consent screens, hosted docs (Swagger UI, Redoc), admin consoles and webhook test pages are documents. Give them a policy written for what they load, typically with `script-src` and nonces or hashes, and keep the blanket `'none'` policy for the JSON routes. Do not loosen the API-wide header to accommodate one HTML page. * **Multiple policies all apply.** If a gateway and the application both send `Content-Security-Policy`, the browser enforces each one, so the effective policy is the stricter combination. Adding a second header can only tighten things, never loosen them. * **Roll out with Report-Only on HTML.** `Content-Security-Policy-Report-Only` reports violations without blocking. It is worth using on documents with a complex policy. For the JSON `'none'` policy there is nothing to test. * **Some directives only work as a header.** `frame-ancestors`, `sandbox` and `report-uri` are ignored in a `` element, so an API must send them in the response header. ## Examples The baseline for a JSON API response: ```http HTTP/1.1 200 OK Content-Type: application/json Content-Security-Policy: default-src 'none'; frame-ancestors 'none' X-Content-Type-Options: nosniff ``` The same baseline on an error, which is where reflected input most often ends up rendered: ```http HTTP/1.1 404 Not Found Content-Type: application/problem+json Content-Security-Policy: default-src 'none'; frame-ancestors 'none' ``` An HTML documentation page served by the same API, with its own policy: ```http HTTP/1.1 200 OK Content-Type: text/html; charset=utf-8 Content-Security-Policy: default-src 'self'; script-src 'self' 'nonce-r4nd0m'; img-src 'self' data:; frame-ancestors 'none'; base-uri 'none'; form-action 'self' ``` --- # Content-Type header > Indicates the media type of the request or response body payload. Source: https://apiguide.dev/headers/content-type Direction: both Standardized: yes Defined in: RFC 9110, Section 8.3 Updated: 2026-07-08 ## What is the Content-Type header? The `Content-Type` header tells the recipient how to interpret the bytes of the HTTP body (e.g. parsing it as JSON, XML, or multi-part form data). ## API Usage & Best Practices * **Use standard types**: Modern JSON APIs should use `application/json` or `application/problem+json` for errors. * **Validate incoming mutations**: If a client sends an unsupported type in a POST/PUT, reject it with `415 Unsupported Media Type`. ## Examples ```http HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 ``` --- # Cookie header > Sends previously stored cookies from the client back to the server. Source: https://apiguide.dev/headers/cookie Direction: request Standardized: yes Defined in: RFC-ietf-httpbis-rfc6265bis-22, Section 5.8.1 Updated: 2026-07-10 ## What is the Cookie header? The `Cookie` request header, defined in RFC 6265, carries the name/value pairs the client previously received via `Set-Cookie` for the current domain and path. It is the mechanism that lets a stateless HTTP server recognize a returning client. ## API Usage & Best Practices * **Cookie sessions vs token auth**: Cookie-based sessions are sent automatically by browsers, whereas token schemes like `Authorization: Bearer` are attached explicitly by the API client, which many APIs prefer for statelessness. * **Mind CSRF**: Because cookies are sent automatically, cookie-authenticated APIs need CSRF protection such as `SameSite` cookies or anti-CSRF tokens. * **Keep it lean**: Send only the cookies a request needs, since large cookie payloads add overhead to every request. ## Examples ```http GET /v1/profile HTTP/1.1 Host: api.example.com Cookie: session_id=abc123; theme=dark ``` --- # Cross-Origin-Resource-Policy header > Tells browsers which sites may load a response through no-cors requests such as img and script tags. Does not affect CORS fetches. Source: https://apiguide.dev/headers/cross-origin-resource-policy Direction: response Standardized: yes Defined in: WHATWG Fetch Standard Updated: 2026-10-17 ## What is the Cross-Origin-Resource-Policy header? The `Cross-Origin-Resource-Policy` (CORP) response header lets a server say which origins or sites may load the response when the browser fetches it in `no-cors` mode: through an ``, `