HTTP 402 Payment Required: what it means and how x402 uses it
402 is the HTTP status code for a request that needs payment before the server will fulfil it. For most of its history it had no standard format. x402 gives it one.
Key takeaways
-
402 Payment Required is a client error: the request is valid, but the server wants payment first.
-
HTTP/1.1 reserved 402 for future use and never defined how payment should work, so each API used it differently.
-
x402 defines the missing pieces: a PAYMENT-REQUIRED header with machine-readable terms and a signed payment on retry.
What 402 Payment Required means
A 402 response tells the client that the request itself is fine but will not be served until payment is made. It belongs to the 4xx family because the client, not the server, has to act next.
402 is different from 401 Unauthorized and 403 Forbidden. 401 asks for credentials, 403 refuses the request outright, and 402 asks for payment.
Why 402 went unused for so long
The code was reserved when HTTP/1.1 was written, with the expectation that some form of digital cash would arrive later. The specification never said what a 402 body should contain or how a client should pay, so browsers never acted on it.
Without a shared format, APIs that did return 402 used it as a plain error: an account ran out of credits, a card was declined, or a plan limit was reached.
When APIs return 402 today
You will see 402 in two broad situations.
- Account billing errors: the key is valid but the balance, quota, or subscription does not cover the request. The fix is to top up or upgrade.
- Pay-per-request quotes: the server returns payment terms, and the client can pay and retry the same request. This is how x402 works.
How x402 turns 402 into a payment flow
x402 puts machine-readable terms in a PAYMENT-REQUIRED header: amount, asset, network, and recipient. A client signs a stablecoin authorization for those terms, sends it back in a PAYMENT-SIGNATURE header, and receives the response with a PAYMENT-RESPONSE receipt.
Because the whole exchange is plain HTTP, an AI agent with a wallet can pay for an API call without signing up or storing an API key.
Handling a 402 in your client
Check for a PAYMENT-REQUIRED header first. If it is there, the response is an x402 quote and an x402 client can pay it. If it is not, read the error body: it usually means the account needs more credits or a different plan.
HTTP 402 FAQ
Is 402 Payment Required an error?
It is a client error in the 4xx range, but it does not mean the request was malformed. It means payment is needed before the server will continue.
What is the difference between 402 and 401?
401 means the server needs valid credentials. 402 means the server needs payment. An API can return 401 for a bad key and 402 for a valid key with no balance.
Do browsers handle 402 automatically?
No. Browsers show a 402 like any other error page. Automatic payment needs a client that understands a protocol such as x402.
Which APIs use 402 with x402?
Any server that implements the x402 protocol. RunAPI returns x402 quotes on its per-call AI model endpoints, so an agent can pay for image, video, music, and audio generation in USDC.
Related pages
Try a 402 you can actually pay
Send a request to a RunAPI per-call endpoint without a key and inspect the x402 quote it returns.