What does HTTP 402 Payment Required mean?

Why am I getting a 402 error?

You get a 402 when the server will not do the work until something is paid. Most often your account balance, credits, or plan is exhausted. On a paid-per-request endpoint, the 402 is the price quote itself.

The status code alone does not tell you which case you hit. Read the response headers and body before you retry anything.

• Out of credits or budget, for example OpenRouter returns 402 when an account or API key has insufficient credits.
• Account frozen or unpaid, for example Shopify returns 402 when a shop is frozen for nonpayment.
• Payment required per request, where the server sends an x402 or MPP payment challenge.

Is 402 an official HTTP status code?

It is registered, but it has no defined behavior. RFC 9110, the current HTTP semantics standard from June 2022, says the 402 code "is reserved for future use." RFC 2616 said the same in 1999.

MDN lists 402 as nonstandard and notes that no standard use convention exists. Browsers show it as a generic 4xx error. That gap is why every API that returns 402 has to document what it means.

How do I tell which kind of 402 I got?

Check for a payment header first. A PAYMENT-REQUIRED header means x402. A WWW-Authenticate header with the Payment scheme means MPP. No payment header and a JSON error body usually means a billing or credits problem.

How should a client handle a 402 response?

Do not retry a 402 in a loop. Unlike a 429 or 503, a 402 will not clear by waiting unless the API says so. OpenRouter, for example, says a 402 without a Retry-After header is not a wait-and-retry case, and its SDKs do not retry it.

• Log the full headers and body, not only the status.
• If there is a payment challenge, compare the price to your budget before paying.
• If you pay, resend the exact same request with the payment header. The challenge was issued for that request.
• If it is a billing error, stop and surface it to a human or top up the account.
• Treat an unknown 402 as a hard failure. Do not guess.

What does an x402 402 response look like?

An x402 402 has a JSON body and a PAYMENT-REQUIRED header with Base64-encoded JSON. We called a Locus x402 endpoint for Alpha Vantage company data on September 29, 2026 without paying.

The body said "Payment required" and asked for a valid x402 v2 exact PAYMENT-SIGNATURE for USDC on Base. The decoded header listed x402Version 2, scheme exact, network eip155:8453 (Base), amount 8000 (USDC has 6 decimals, so $0.008), the USDC contract, the seller address, and a 300 second timeout.

What does an MPP 402 response look like?

An MPP 402 uses the Payment HTTP authentication scheme. The challenge is in the WWW-Authenticate header, and the body is a problem+json error.

We called a Locus MPP endpoint for Parallel search on September 29, 2026 without paying. The header named method tempo and intent charge, with an ID, an expiry, and a Base64url request field. That field decoded to an amount of 8000, the USDC.e token on Tempo, chain ID 4217, and the recipient address.

How is 402 different from 401 and 403?

401 means the server does not know who you are. 403 means it knows and says no. 402 means it would say yes after payment.

MPP spells this out. It uses 402 for a payment requirement, 401 for an authentication failure, and 403 for a policy denial. If you see 401 on a paid API, fix your credentials first. Paying will not help.

How do x402 and MPP give 402 a payment format?

Both protocols fill the gap RFC 9110 left open. They define what a 402 response carries and how the client proves payment on the retry.

x402 uses PAYMENT-REQUIRED, PAYMENT-SIGNATURE, and PAYMENT-RESPONSE headers and settles stablecoin payments through a facilitator. MPP uses WWW-Authenticate, Authorization, and Payment-Receipt headers, and supports stablecoins on Tempo plus cards through Stripe. The x402 and MPP guides cover each one.

How can an AI agent pay a 402 automatically?

An agent needs a wallet or payment method, a client that reads the challenge, and a spending limit. Without a limit, an agent that pays every 402 will pay whatever it is asked.

Locus Pro does this for your agent. It pays listed x402 and MPP services from one prepaid credit balance, so the agent never holds crypto. Pass max_charge_credits as a ceiling. If the live price is higher, Locus declines before dispatch and charges nothing.