HTTP 402 Payment Required: What It Means and How to Handle One

HTTP 402 Payment Required means the server wants payment before it will answer. The standard only reserves the code, so its meaning depends on who sent it. Several large APIs use it for a billing problem on your account. Payment protocols such as x402 use it for a machine-readable price that a program or AI agent can pay before retrying.

What the Standard Says

The whole definition in RFC 9110, the current HTTP standard from June 2022, is one sentence: "The 402 (Payment Required) status code is reserved for future use." The IANA registry points to that section, and nothing else in the standard says what a 402 response should contain.

MDN calls it nonstandard and notes that "no standard use convention exists." Browsers do nothing special with it: a 402 is shown like any other 4xx error. Programming languages still name it, as HTTPStatus.PAYMENT_REQUIRED in Python and StatusPaymentRequired in Go, so any server can send one.

Where 402 Came From

The code is older than the RFC that reserved it.

• In 1992, an early list of HTTP status codes, now archived by the W3C, included "PaymentRequired 402": the response would name the "charging schemes acceptable," and the client could retry "with a suitable ChargeTo header."
• In May 1996, HTTP/1.0 (RFC 1945) left 402 out. Its list jumps from 401 to 403.
• In January 1997, RFC 2068, the first HTTP/1.1 spec, brought it back as "reserved for future use." RFC 2616 in 1999 and RFC 9110 in 2022 kept the same wording.
• On May 6, 2025, Coinbase announced x402, an open protocol that uses the original 402 for stablecoin payments. The Linux Foundation took it over as the x402 Foundation on April 2, 2026.

Some guides say 402 has been reserved "since 1995" or was defined "in 1996." The RFC record puts it in January 1997, eight months after HTTP/1.0 had left it out. We think the 1992 idea, a server stating its price and a client paying on retry, is close to how the protocols built on 402 work now.

The Two Kinds of 402 You Will See

Because the standard never filled in the details, two uses grew up side by side. In one, 402 reports a billing problem with an account you already have. In the other, 402 is a price quote for this one request, written so software can pay it.

The first four rows come from each company's own error docs (Stripe, Shopify, Google, DeepSeek, OpenRouter). Stripe calls its 402 "Request Failed": the parameters were valid but the request failed. MDN describes the same habit more generally: some payment APIs use 402 "as a generic catch-all for failed payment requests."

How to Tell Which One You Got

Look at the headers before the body.

1. A PAYMENT-REQUIRED header means an x402 server. In x402 V2 it holds the price as Base64-encoded JSON: accepted payment schemes, amount, network and the address to pay (x402 docs).
2. A WWW-Authenticate: Payment header means the Machine Payments Protocol (MPP), which Tempo and Stripe launched on March 18, 2026. Its "Payment" authentication scheme was written up as an individual Internet-Draft with no formal IETF standing; as of November 4, 2026, the IETF lists that draft as expired.
3. A WWW-Authenticate header with a token and a Lightning invoice means L402.
4. None of these, and a JSON error such as an expired card or insufficient credits, means a billing 402. Read the error code in the body and fix the account.

Here is a real x402 challenge we captured on November 4, 2026, from a small quote service, with the header decoded and trimmed:

HTTP/2 402
payment-required: eyJ4NDAyVmVyc2lvbiI6Mi...   (Base64)

decoded:
{
  "x402Version": 2,
  "accepts": [{
    "scheme": "exact",
    "network": "eip155:8453",
    "amount": "5000",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "payTo": "0x589a...B3d8",
    "maxTimeoutSeconds": 60
  }]
}

eip155:8453 is Base mainnet, and that asset is USDC, which has 6 decimals there (x402 network list). So 5000 means $0.005 for one call. The JSON body said the same thing in plain words: "PAYMENT-SIGNATURE header is required."

How to Fix a 402

What to do depends on where you sit.

On a Website or App

Look for a billing problem: an expired card, a lapsed plan, or an unpaid balance. Update the payment method or plan in your account settings, or contact the service if it is not yours to change.

Calling an API

Read the error code in the body first. It usually names the cause, and the fix is in your billing settings: top up, raise a budget, or change the card. Don't loop on it. OpenRouter's docs say a 402 without a Retry-After header "is not a wait-and-retry case," and that the OpenAI, Anthropic, Vercel AI and OpenRouter SDKs do not retry a 402 on their own.

Building an Agent That Pays

Treat a challenge 402 as a quote. Decode it, check the amount and network against the budget you gave the agent, pay, and retry the same request with the PAYMENT-SIGNATURE header. Expect older servers too: x402 V1 used an X-PAYMENT header and network names like base-sepolia, where V2 uses CAIP-2 IDs like eip155:84532 (migration guide). Whether the money settles on-chain within the same round trip depends on the payment scheme the server picked.

Running the API

Our recommendation is to send 402 only when paying would fix the request. Use 401 when credentials are missing or invalid, 403 when the server refuses and payment would not change that, and 429 for rate limits (RFC 6585). Put a machine-readable reason in the body. If you want software to pay you per call, a 402 challenge in a format clients already parse, such as x402, saves every client from guessing.

What Live x402 Services Send Back

To see what a payment-challenge 402 looks like in practice, we sampled Coinbase's public x402 Bazaar directory on November 4, 2026. It listed 112,162 resources. We took 20 listings at each of 25 evenly spaced points (500 listings) and sent each one unpaid request: a GET, or a POST with an empty JSON body where the listing said POST.

The 340 dead listings all belonged to a single host, which returned HTTP 530 or nothing at all. A directory entry is a claim, and it does not prove a service is up.

The 157 that answered 402 were spread over 33 hosts, and every one carried the V2 PAYMENT-REQUIRED header. Forty of them, on 8 hosts under two domains, also put a V1-style copy in the JSON body of the same response ("network": "base", maxAmountRequired), so old and new clients can both read it. Six hosts, including the search API Exa, offered an MPP WWW-Authenticate: Payment challenge on the same 402 as well, which lets one response serve clients of either protocol.

This is a self-listed directory, so the numbers describe what we saw on one day, not the web at large. The pattern is still useful: clients should read the header first, accept a V1 body, and look for more than one protocol in the same response.

Where QDay Fits

QDay is an EVM-compatible network built for per-request agent payments, with a path to post-quantum ML-DSA-65 signatures. Aevum Testnet is live today, and x402 support and the agent payment features are coming soon, with mainnet planned for 2027. For the bigger picture of how agents pay, read how AI agents pay.