HTTP 402 Payment Required - a practical guide for APIs

Why 402 now

APIs increasingly serve automated clients and agents. 402 makes “paid access” programmable, observable, and testable in the same loop as your normal requests.

Anatomy of a 402 response

• status: 402
• detail: human-readable reason
• payment: a minimal JSON hint (protocol, amount, currency, reference, instructions)

HTTP/1.1 402 Payment Required
Content-Type: application/json; charset=utf-8
Cache-Control: no-store

{
  "detail": "Payment required to access this resource.",
  "payment": {
    "protocol": "x402",
    "amount": "0.10",
    "currency": "USDC",
    "reference": "demo-402-abc123",
    "instructions": "Pay using your client wallet and present a receipt in the follow-up request."
  }
}

Design rules we follow

1. Keep it small: only fields your client truly needs.
2. Reference everything: include a stable reference you can map to an entitlement.
3. Be explicit about expiry: short-lived challenges reduce replay risk.
4. Deterministic errors: return clear reasons for insufficient/expired/invalid receipts.
5. Log enough to audit: challenge ID, receipt hash, verification outcome.

Flow: request → 402 → pay → receipt → access

1. Client requests a priced resource.
2. Server returns 402 with a payment hint.
3. Client pays, obtains a receipt/proof.
4. Client retries with the receipt in headers or body.
5. Server verifies and returns 2xx or a precise error.

Common pitfalls

• Leaking pricing logic into every handler. Centralize challenge creation.
• Opaque errors. Machines need deterministic reasons.
• No mapping from reference to entitlement. Keep a ledger.

FAQ