402 Payment Required 4xx
Reserved for future use; in practice, often repurposed by APIs to indicate a payment-related failure.
What does 402 mean?
A 402 Payment Required is one of the strangest entries in the HTTP status code registry: it was reserved from the very beginning of HTTP's design for future use, with the loose idea of supporting digital payment/micropayment schemes that, decades later, still haven't become a standardized part of the web's core protocols.
As a result, 402 sits in an unusual position — it's officially defined and reserved, but the HTTP specification itself doesn't define what using it actually means in practice. This has left the door open for individual APIs to repurpose it for their own payment-related use cases, most notably Stripe, which uses 402 for certain payment-failure scenarios.
How a 402 behaves
- There's no standardized body format or required headers — because the spec doesn't define concrete semantics beyond "reserved for future use," any specific meaning is entirely up to the API using it
- It's not cacheable in any meaningful standardized sense
- Its practical meaning is API-specific — unlike almost every other status code in this reference, you genuinely need to check the specific API's documentation to know what 402 means for that API, since there's no universal convention
Common causes (in APIs that use it)
If you're building the API:
- Some payment-processing APIs use 402 specifically for failed payment attempts — distinguishing "the request was valid, but the actual payment transaction failed" from a generic 400 (malformed request) or 422 (validation failure)
- A small number of APIs use 402 more broadly for "this account's subscription/billing is in an invalid state" (e.g., expired trial, unpaid invoice) blocking access to features
If you're calling an API:
- You're using an API (most notably payment-processing APIs like Stripe) that specifically documents 402 for payment failures — check that API's documentation for the precise meaning, since it won't be the same across different providers
- A SaaS API might be returning 402 to indicate your account's billing status is preventing the requested operation (e.g., a free trial expired, or a subscription payment failed)
If you're a website visitor:
- Extremely unlikely to encounter this directly — 402 is essentially an API-to-API or API-to-developer signal, not something that surfaces in typical browsing
How to fix it
As an API/website builder:
- If you choose to use 402, document its specific meaning thoroughly in your API docs — don't assume consumers will know what it means, since there's no universal convention to rely on
- Consider whether a more universally-understood code (like 403 for "access blocked due to account status," or a custom error code/message within a 4xx response) might communicate your intent more clearly to developers unfamiliar with your specific 402 convention
As an API consumer:
- Check the specific API's documentation for what 402 means for that API — don't assume it follows a pattern you've seen elsewhere
- For payment-processing APIs, a 402 typically indicates the payment itself was declined/failed — handle this distinctly from request-format errors (400/422), often by prompting the user to try a different payment method
As a website visitor:
- If you somehow encounter a 402-related message, it likely relates to a billing/subscription issue with the service you're using — checking your account's billing/payment status is the relevant next step
402 vs 403
| 402 Payment Required | 403 Forbidden | |
|---|---|---|
| Standardized meaning | None — reserved for future use, repurposed inconsistently | Well-defined — authenticated but not authorized |
| Typical real-world use | Payment-processing failures (where used at all) | General permission/access denial |
| How common is it | Rare — most APIs avoid it due to ambiguity | Extremely common |
Real-world examples
Stripe's API uses 402 specifically for situations where a request was valid and authenticated, but an actual payment/charge attempt failed (e.g., a card was declined) — this is one of the most well-known real-world uses of 402, and is often cited as the example of this code being used meaningfully. Most other APIs avoid 402 entirely, preferring more universally-understood codes (400, 402, 422) or custom error fields within standard response bodies for billing-related issues.
SEO implications
402 has no relevance to page-level SEO — it's an API-specific code that essentially never appears in the context of indexable web content.
FAQ
Why is 402 so rarely used?
The HTTP specification reserves 402 for future use without defining concrete semantics — there's no standardized meaning for developers to rely on. This ambiguity has led most APIs to avoid it in favor of codes with well-established, universally understood meanings.
Does 402 mean the same thing across different APIs?
No — and this is unusual among status codes. Because the spec doesn't define concrete semantics, each API that chooses to use 402 effectively invents its own meaning. Always check the specific API's documentation rather than assuming based on other APIs you've used.
Is 402 related to cryptocurrency or "web monetization" proposals?
There have been various proposals over the years (some related to micropayments, content paywalls, and machine-to-machine payment protocols) that reference 402 as a conceptual fit for "payment needed to access this resource" — but none of these have become a widely adopted standard that defines concrete, universal behavior for 402.
If I get a 402 from an API, what should I do?
Check that specific API's documentation immediately — given the lack of standardization, the correct response depends entirely on what that particular API has defined 402 to mean (most commonly, a failed payment/charge attempt).
Will 402 ever get a standardized meaning?
It's possible — there have been periodic discussions and proposals in the broader web standards community about formalizing payment-related HTTP semantics, but as of now, nothing has been widely adopted that gives 402 a universal, standardized meaning beyond "reserved."
Fun fact
402 has been "reserved for future use" since the earliest versions of the HTTP specification — making it, depending on how you count, one of the longest-standing "TODO" items in any widely-used internet protocol, with the web's actual payment infrastructure having developed almost entirely outside of HTTP status codes (think payment gateways, third-party processors, and application-level APIs) rather than through this reserved code.