HTTP Status Codes
HTTP 402 Payment Required
Payment Required
The 402 code is a non-standardized response originally intended for digital cash implementations, but frequently used by APIs to signal billing limitations.
Visual summary
A quick reference view of how HTTP 402 works: A paywall or toll booth blocking the path until a financial or quota requirement is met.
What 402 Means
The shortest useful reading of this status code.
Payment Required.
This status falls into the 4xx class, indicating a client-side error outcome for the request.
Quick read
Payment Required
The 402 code is a non-standardized response originally intended for digital cash implementations, but frequently used by APIs to signal billing limitations.
Technical Context
How this status behaves without turning the page into a repair guide.
Standard usage
This status indicates that the client's request cannot be processed until a payment is made or a quota is increased.
Technical nuance
It uniquely communicates financial or tier-based restrictions rather than permissions (403) or authentication (401).
Implementation detail
The 402 status code has existed in the HTTP specification since 1997 but was left intentionally undefined as a placeholder for a micropayment layer that never materialized in the early web. Because no standard convention was established, individual services adopted it with their own semantics -- Stripe uses it for declined charges, Shopify for frozen stores due to unpaid invoices, and various API providers for exhausted quotas or billing limitations.
Architecture
In 2025 and 2026, protocols like x402 and Stripe's Machine Payments Protocol began giving 402 a concrete, interoperable meaning: an unpaid request receives a 402 response containing a machine-readable payment challenge with the exact price, currency, and payment instructions. The caller can then pay programmatically and retry the original request, transforming 402 from a dead-end billing error into a live, actionable payment negotiation.
Related HTTP Codes
Nearby HTTP status codes help clarify how 402 differs inside the same response family.
402
Payment Required
The 402 code is a non-standardized response originally intended for digital cash implementations, but frequently used by APIs to signal billing limitations.
400
Bad Request
the server cannot process the request because it is malformed
401
Unauthorized
valid authentication credentials are missing for the target resource
403
Forbidden
the server understood the request but refuses to authorize it
Common Causes
Subscription expired
A common condition that triggers a 402 response when the web server evaluates the transaction.
Daily quota exceeded
A common condition that triggers a 402 response when the web server evaluates the transaction.
Premium feature access blocked
A common condition that triggers a 402 response when the web server evaluates the transaction.
Typical Scenarios
A developer exceeds the freemium API rate limit
A user attempts to read a paywalled article without an active subscription
A subscription-based SaaS API rejects a request because the organization's billing plan was downgraded after a failed credit card charge
An AI agent calling a metered API endpoint receives a 402 response with a structured payment challenge quoting the cost per request
What To Know
Verification of the API provider's billing dashboard or account subscription status is the standard path to resolving these limitations.
Frequently Asked Questions
Common interpretation questions about HTTP 402.
It indicates that the service requires a payment or tier upgrade to fulfill the request.
403 means you are authenticated but not permitted to access the resource -- no credential or payment will help. 402 means access is available but gated behind a payment, and once the payment condition is met, the request should succeed.
No browser has native UI for 402. A user would see a generic 4xx error. The status code is designed for programmatic clients (APIs, SDKs, AI agents) that can read the response body and act on payment instructions.
In the x402 protocol, a client requests a resource, the server responds with 402 containing a machine-readable payment challenge (price, currency, payment address), the client pays programmatically and retries the original request with proof of payment, and the server verifies and returns the requested content with a 200 status.