HTTP 402 Payment Required

Quick reference

The original intent

RFC 2068 and RFC 2616 (the original HTTP/1.1 specifications) included 402 with a note that it was “reserved for future use.” The working group anticipated a future where micropayment protocols would be standardized into HTTP — servers requesting payment for a resource, clients settling it automatically. The digital-commerce experiments of the 1990s (Millicent, SET-based systems, and similar) were the backdrop.

That HTTP-level payment layer never standardized. Commerce moved to out-of-band systems — payment gateways, checkout pages, and subscription platforms — rather than HTTP payment negotiation. RFC 9110 keeps 402 reserved and deliberately assigns it no semantics, which is exactly why its meaning today lives in the response body and in conventions built on top of it.

Why 402 matters again

The conditions the original spec imagined finally exist — metered access, programmatic clients, and a need to charge per request without a human at a checkout page. Several forces are bringing 402 back into everyday use:

• API monetization. Pay-per-call and metered APIs need a way to say “this call costs money you don’t currently have” that a client can act on.
• SaaS usage credits. Credit-based products (AI inference, data, compute) need to signal an empty balance distinctly from auth and rate-limit failures.
• Paid model and API access. Premium models, datasets, and endpoints are increasingly gated behind payment or entitlement checks rather than flat plans.
• AI agents paying for what they use. Autonomous agents need to pay for the tools, APIs, content, and MCP servers they call — often with no human in the loop to click “buy.”
• From payment pages to payment challenges. Instead of redirecting a browser to checkout, a service can return a structured 402 a program reads and acts on — the same shift 401 represents for authentication.

Use cases you’ll actually run into

• A metered API runs out of quota mid-integration. Your app calls a geocoding, search, or inference API on a prepaid plan. The first call past the quota returns 402 with credits_remaining: 0 and a top-up URL — so the client shows “add credits” and recovers, instead of choking on an unexplained 500 or a dead-end 403.
• An AI agent pays for a tool or MCP server on its own. A multi-step agent needs a paid data API or a paid MCP tool to finish a task. The server answers 402 with machine-readable terms; the agent checks its budget, pays, and retries — no human at a checkout page. This is the exact pattern x402 is built for.
• Pay-per-use content behind an API. A news, research, or dataset API returns 402 with a price and a payment link for an item the caller hasn’t bought yet — letting the client offer a one-tap purchase instead of a blanket “forbidden.”
• A subscription lapses or a card fails. Instead of a permanent-sounding 403, a SaaS API returns 402 with state: grace_period and a billing URL, so the integrating app prompts “update your payment method” and access restores the moment billing is fixed.
• Free tier exhausted, upgrade in product. Hitting a Pro-only endpoint on a Starter plan returns 402 with required_plan: pro and an upgrade URL, so the product shows a contextual upgrade prompt right where the user hit the wall — not a generic error.

Adoption is still uneven: some APIs already use 402 this way, while others overload 403 (forbidden) or 429 (rate limited) for billing problems. Standardizing on 402 for “payment can fix this” is what makes these flows programmatically recoverable — and what protocols like x402 formalize.

The x402 revival

x402 is an emerging payment protocol built on top of the HTTP 402 status code. Its goal is to make “pay for this request” something software can do directly: a server responds with 402 Payment Required plus machine-readable payment instructions, and a client, app, or AI agent can satisfy the payment programmatically and retry the original request with proof.

x402 is associated with Coinbase, and an ecosystem of tooling is emerging around it — including support and examples on Cloudflare Workers and agent frameworks that let an edge API issue and verify 402 challenges. Settlement is typically done with stablecoins, but the protocol’s relevance here is structural, not financial: it gives 402 the machine-readable shape the original HTTP authors never specified.

Important distinction: x402 is not the same thing as HTTP 402. HTTP 402 is the status code defined by the HTTP specification. x402 is a higher-level protocol that uses that status code to carry payment terms and proofs. You can return HTTP 402 from an API today without adopting x402, and x402 is one (increasingly visible) way to give 402 a concrete, interoperable meaning.

How an x402-style flow works

The pattern mirrors how a 401 authentication challenge works, with payment in place of credentials:

1. The client requests a paid resource.
2. The server returns HTTP 402 Payment Required.
3. The response body includes payment terms — amount, accepted assets/networks, the recipient, and the resource being paid for.
4. The client or AI agent pays using a supported payment rail.
5. The client retries the original request, attaching proof of payment.
6. The server (often via a facilitator) verifies the payment and returns the protected content or API result.

An illustrative exchange (field names follow the x402 specification; shown here for shape, not as a spec quote):

GET /api/v1/inference HTTP/1.1
Host: api.example.com

HTTP/1.1 402 Payment Required
Content-Type: application/json

{
  "x402Version": 1,
  "accepts": [
    {
      "scheme": "exact",
      "network": "base",
      "maxAmountRequired": "10000",
      "asset": "USDC",
      "payTo": "0xRecipientAddress...",
      "resource": "/api/v1/inference",
      "description": "One inference call",
      "maxTimeoutSeconds": 60
    }
  ]
}

The client pays, then retries with a payment payload attached:

GET /api/v1/inference HTTP/1.1
Host: api.example.com
X-PAYMENT: <base64-encoded signed payment payload>

HTTP/1.1 200 OK
Content-Type: application/json

{ "result": "..." }

402 for humans vs 402 for machines

The same status code serves three audiences, and a good implementation accounts for all of them:

• For human users, 402 usually means upgrade your plan, renew a subscription, add credits, or fix a billing problem. The right experience is a clear message and a link to a billing or checkout page.
• For API clients, 402 should expose a structured JSON body: a machine-readable reason, the current state (plan, credits, account status), what payment, plan, or credits are required, and an action URL.
• For AI agents, 402 is becoming a programmatic payment challenge, much like 401 is an authentication challenge. The agent reads the terms, decides within its spending policy, pays, and retries — without a human at a checkout page.

402 vs 401 vs 403 vs 429

The distinction drives client behavior: 401 triggers an authentication flow, 402 a payment or upgrade flow, 403 a permanent permission denial, and 429 a backoff-and-retry. See also 401 vs 403 (authentication vs authorization).

Common 402 response examples

Because 402 has no standard structure, the body carries the meaning. Useful, machine-readable shapes:

Insufficient credits

HTTP/1.1 402 Payment Required
Content-Type: application/json

{ "error": {
  "code": "insufficient_credits",
  "message": "Your credit balance is insufficient for this request.",
  "credits_required": 10,
  "credits_available": 3,
  "action_url": "https://platform.example.com/billing/credits"
}}

Subscription expired

HTTP/1.1 402 Payment Required
Content-Type: application/json

{ "error": {
  "code": "subscription_expired",
  "message": "Your subscription lapsed and the account is in a grace period.",
  "state": "grace_period",
  "grace_ends": "2026-06-15",
  "action_url": "https://example.com/billing"
}}

Plan upgrade required

HTTP/1.1 402 Payment Required
Content-Type: application/json

{ "error": {
  "code": "plan_limit_exceeded",
  "message": "Advanced analytics requires a Pro plan or higher.",
  "current_plan": "starter",
  "required_plan": "pro",
  "action_url": "https://example.com/pricing"
}}

Payment method failed

HTTP/1.1 402 Payment Required
Content-Type: application/json

{ "error": {
  "code": "payment_method_failed",
  "message": "The card on file was declined.",
  "last_attempt": "2026-06-08",
  "action_url": "https://example.com/billing/payment-methods"
}}

x402-style payment required (machine-readable terms for programmatic payment)

HTTP/1.1 402 Payment Required
Content-Type: application/json

{ "x402Version": 1,
  "accepts": [
    { "scheme": "exact", "network": "base", "maxAmountRequired": "10000",
      "asset": "USDC", "payTo": "0xRecipientAddress...",
      "resource": "/api/v1/inference", "description": "One inference call" }
  ]
}

Technology surrounding modern 402

A quick glossary of the moving parts you will encounter when 402 is used for real billing or programmatic payments:

Implementation guidance

Because the spec gives 402 no semantics, the quality of your implementation lives entirely in the response:

• Do not rely on the status code alone. Always return a body that explains the failure.
• Return structured JSON a client can parse — not just a human sentence.
• Include a machine-readable error code (for example insufficient_credits, subscription_expired, plan_limit_exceeded, payment_method_failed).
• Include the payment requirement — amount, plan, or credits needed, plus accepted rails when relevant.
• Include current account, credit, or plan state when it is safe to expose, so clients can render accurate prompts.
• Include an action URL for humans — a billing portal, upgrade page, or payment link.
• Include retry guidance — whether the request can be retried immediately or after a short propagation delay.
• Use 401 for unauthenticated callers, not 402.
• Use 403 when payment will not solve the problem (a permission or policy denial).
• Use 429 for rate limits, not 402.
• Use 402 only when payment, credits, or billing state can actually resolve the failure.

Security and risk considerations

Once 402 carries real payments — especially automatic ones — the response becomes security-sensitive. Practical points to design for:

• Replay attacks. A captured payment proof should not be reusable; bind proofs to a nonce and a short expiry.
• Payment proof binding. Tie each proof to the specific request, amount, and payer so it cannot be applied elsewhere.
• Endpoint/resource binding. Scope a payment to the resource it was for — paying for one endpoint should not unlock another.
• Double-spend / duplicate payment. Detect and reject duplicate submissions; make verification idempotent.
• Paid-but-denied failures. Plan for a payment that succeeds while access still fails — refund or retry, and log it.
• Unpaid-but-served failures. Never release protected content before verification completes.
• Agent spending limits. Bound automatic payments with per-request and cumulative caps.
• User consent. Make sure a human authorized the spending policy an agent acts under.
• Audit logs. Record what was charged, for what, and to whom, for reconciliation and disputes.
• PII leakage in payment metadata. Keep personal and financial data out of error bodies and metadata that may be logged.
• Authorization is separate from payment. A valid payment does not prove the payer is authorized — check both.

Frequently asked questions

Is HTTP 402 finally being used?

Yes, increasingly. For years 402 was effectively dormant, but usage-based APIs, credit-based SaaS products, and paid model and data access now return it to signal a payment or billing problem. Emerging protocols such as x402 push it further by turning 402 into a structured, machine-readable payment challenge for apps and AI agents.

What is x402?

x402 is an emerging payment protocol built on top of the HTTP 402 status code. A server responds with 402 plus machine-readable payment terms, and a client, app, or AI agent can pay programmatically and retry the request with proof of payment. It is associated with Coinbase, with tooling emerging around Cloudflare Workers and AI-agent frameworks.

Is x402 the same as HTTP 402?

No. HTTP 402 is the status code defined by the HTTP specification. x402 is a higher-level protocol that uses the 402 status code to carry payment instructions and proofs. You can use HTTP 402 in an API without using x402 at all.

What does HTTP 402 mean?

The HTTP specification reserves 402 for payment and assigns it no fixed semantics, so the meaning comes from the response body. In practice it means the request cannot be fulfilled until a payment, credit, plan, or billing issue is resolved. Read the JSON body for the specific reason and the action required.

Should APIs use 402 for unpaid invoices?

It can be reasonable when an unpaid invoice blocks access and paying it restores access. Return a structured body explaining the billing state and an action URL to settle the invoice. If the account is suspended for reasons payment cannot fix, prefer 403. If the caller is simply not authenticated, use 401.

Should 402 be used instead of 403?

Use 402 only when paying, upgrading, or adding credits will resolve the failure. Use 403 when the caller is authenticated but not permitted and payment would not change that. The distinction lets clients show an upgrade or billing prompt for 402 versus a permission error for 403.

Can AI agents handle 402 automatically?

That is a primary goal of protocols like x402. If the 402 response carries machine-readable terms, an agent can evaluate them against its spending policy, pay within limits, and retry with proof. Automatic handling should always be bounded by spending limits, user consent, and audit logging.

Is 402 only for crypto or stablecoins?

No. 402 is payment-rail agnostic. Most current production use is ordinary billing such as credits, plan limits, and failed subscription payments resolved through card-based billing portals. x402 happens to use stablecoin settlement, but the status code itself does not require any particular payment method.

Is 402 a standard HTTP code?

Yes, it is registered in the IANA HTTP Status Code Registry, but the specification marks it as reserved with no defined semantics. There is no standard wire format for 402 requests or responses, which is why the response body and conventions like x402 matter.

Related guides

HTTP 401 Unauthorized · HTTP 403 Forbidden · HTTP 429 Too Many Requests · 401 vs 403 — authentication vs authorization

Standards reference

Definitions from the IANA HTTP Status Code Registry and RFC 9110 §15.5.3. The x402 sections describe an emerging, third-party protocol and are illustrative, not a specification quote. Human-readable guidance by ErrorLookup. · HTTP 402 quick reference →