HTTP 402 Payment Required explained

HTTP 402 Payment Required is a client error status code reserved for when a requested resource needs payment before it can be served. Unlike most status codes, it was never formally defined by the HTTP specification. RFC 9110 keeps it reserved for future use, which leaves its exact wire behaviour to whoever implements it, and that has shaped how sites and APIs actually use it.

What 402 signals

In the status-code family, 402 sits alongside the other 4xx client errors: like 401, 403, and 404, it tells a client the request was not completed for a reason on the client's side. The RFC reserves it specifically for digital cash or micro-payment systems, meaning "the content is not available until the client pays". No browser handles it specially, and a browser will describe it only as a generic 4xx error, so a visitor never sees a friendly "payment required" message from the browser itself.

Because the meaning is reserved and not defined, the header it should pair with is not fixed. That is different from the other codes, which have concrete syntax. Where a payment protocol does attach a challenge, the practical pattern is a WWW-Authenticate challenge combined with the 402, in the same spirit as a 401 challenge for authentication, because payment is a form of authorisation to the resource.

How it is used today

In practice 402 has two main lives. Some payment gateways return it as a catch-all for a failed payment request (for example a declined card), which is convenient for the API but semantically loose. More recently, 402 has become the foundation of machine-to-machine payment protocols such as the Machine Payments Protocol and the x402 framework. They approach the wire challenge differently: the Machine Payments Protocol responds to a resource request with 402 plus a WWW-Authenticate: Payment challenge, while x402 uses its own PAYMENT-* headers in place of that challenge. In both cases the client pays and retries with proof, and the server returns the resource. These layered protocols are designed for AI agents and pay-per-call APIs, so a paid API can signal the exact requirement on the wire rather than through a human portal.

For that reason, expecting a 402 while cURLing a public site returns nothing out of the ordinary; without the header and challenge of a specific protocol, a browser or client just reports a 4xx. Read it as "payment is required to proceed" and only act on a specific protocol's challenge if that challenge is present.

Compare the codes

Use the broader status list to place 402 next to its neighbours:

The useful distinction is that 401 and 403 are about identity and permission, while 402 is about payment as a condition of access. When your own service genuinely needs payment before content, returning a 402 with a documented challenge is a defensible modern choice, but because it is not standardized, a plain 403 with a clear message and redirect to a checkout is the more interoperable default for most sites. Keep the response to a client that cannot pay graceful rather than relying on the browser to explain a rare 402, and link that response back to a usable payment flow rather than leaving the client at an unexplained error.