Dashboard
EN
Start free

HTTP 402

the status code an x402 server returns with payment requirements (price, asset, network, payTo).

HTTP 402 Payment Required is a status code that HTTP reserved decades ago without defining how payment should work, and for years almost nothing used it. Today it has two common meanings worth keeping apart, because the same number can mean “top up your account” or “here is a price, pay it now”.

Meaning 1: your account is out of credit

Many APIs, FastAF’s API-key REST endpoints included, return 402 when an account does not have enough credits for a request. On FastAF the body is {"error": {"code": "insufficient_credits", ...}}. It is a billing error: someone has to add credit or pick a cheaper option, and retrying the same call will not help.

Meaning 2: a machine-readable payment challenge

Under the x402 protocol a 402 is not an error but an offer. The body and the PAYMENT-REQUIRED header describe exactly what the server accepts. On FastAF, a 402 for GET /x402/v1/zillow?url=... quotes amount: 5000 USDC units on Base ($0.005), the receiving address and a 300-second validity window. The client is expected to pay and retry. An unpaid request with a wrong parameter also gets the 402, with invalid_parameters saying what to fix.

How do you tell them apart?

Check Credit error x402 challenge
Path /v1/... with an API key /x402/v1/... without a key
Header no PAYMENT-REQUIRED PAYMENT-REQUIRED present
Body error code insufficient_credits accepts array with amount, asset, network, payTo
Right reaction top up or reduce cost sign and retry, if within budget

Example: handling 402 in an agent tool

if status == 402 and "PAYMENT-REQUIRED" in headers:
    quote = decode(headers["PAYMENT-REQUIRED"])
    if price(quote) <= budget: pay_and_retry(quote)
    else: stop("over budget")
elif status == 402:
    stop("account needs credits")

Is reading a quote expensive?

No. On FastAF the 402 challenge is produced before any upstream fetch, so reading a quote is fast and costs nothing.

Which status codes are different?

402 is not 401 (missing or invalid credentials), 403 (forbidden) or 429 (rate limited, usually with Retry-After). A 402 on an x402 route never means your key is wrong: those routes do not take keys.

Related: x402 and agent payments · Pay-per-call API

Related terms

  • x402: x402 is a protocol for paying for HTTP resources using a payment challenge and a signed retry.
  • MCP: Model Context Protocol (MCP) standardizes how AI applications discover and invoke tools and access context.
  • Pay-per-call API: A pay-per-call API charges for individual API requests rather than requiring a recurring subscription.

What it costs: FastAF pricing and credit packs · x402 price list per call

Frequently asked questions

What is HTTP 402?

the status code an x402 server returns with payment requirements (price, asset, network, payTo).

Related