402 Payment Required: Not an Error, a Gate

Problem

You expected a 200, and you got 402 Payment Required. The instinct is to debug it like an error — check the payload, re-read the docs, retry with different headers. Stop. A 402 is almost never a bug, and treating it like one wastes the afternoon.

RFC 9110 §15.5.3 defines the code in a single, strange sentence: the 402 (Payment Required) status code is reserved for future use. That’s the entire specification. The original idea, going back to the mid-90s, was a standard way for a server to say “pay me first” — a hook for digital cash that never got built. So the number was reserved and the protocol around it was left blank: no standard header to name the price, no defined format for the payment challenge.

That blank is why 402 confuses people. Because the spec never nailed down what it means, every service that needed a machine-readable “you owe money” filled in its own definition. The upshot is that 402 is not one condition. It’s a family of deliberate gates, and the fix is figuring out which gate you hit, not patching your request.

Symptoms

• The status line reads 402 Payment Required, usually with a JSON or HTML body explaining the specific reason — an unpaid invoice, an exceeded quota, a required subscription.
• It appears where a request used to succeed, or on an endpoint documented as “premium” / “paid tier” while free endpoints on the same host return 200.
• Retrying with the same credentials changes nothing — because nothing about the request is wrong.
• For a site owner: every page starts returning 402 at once, which points at a platform-level freeze rather than a single endpoint.

Top 3 Causes

1. A metered API cut you off at the quota - The most common developer-facing case. You’re on a free or capped plan, you crossed the monthly request limit or ran out of prepaid credits, and the API now answers 402 instead of serving data. The response body names the limit; the fix is to upgrade the plan, buy credits, or wait for the quota window to reset. Your code is fine — your budget ran out.
2. A hosted platform froze the account over billing - The site-owner case. A commerce or hosting platform with an overdue balance freezes the whole property and serves 402 to visitors. Shopify’s API is the documented example: a frozen shop returns 402 until the administrator settles the outstanding balance. Nothing in your store’s code changed; a payment lapsed.
3. A native payment protocol is asking you to pay, on purpose - The newest case, and the one that actually uses 402 the way the code was originally imagined. Schemes like L402 (a Lightning invoice plus a capability token) and x402 return 402 with a payment challenge in the response, expecting a client — increasingly an automated agent — to pay and retry with proof. Here the 402 isn’t a failure at all; it’s step one of a paywall handshake, and the body tells you exactly how to pay.

Diagnose with DechoNet

• HTTP Check shows the raw status line, response headers, and the start of the body for any URL. That’s where the reason lives: a 402 almost always ships an explanation — an invoice ID, a quota message, or a payment challenge — and reading it tells you which of the three causes you’re looking at. If a plain page returns 402 across the whole host, you have a platform freeze; if only a specific paid endpoint does, you have a quota or paywall.
• Confirm the block is intentional, not a fluke, by checking the response headers for Content-Type and any custom X-* fields the platform uses to describe billing state. A 402 with a clean, structured body is a designed gate; a 402 with a generic error page is a platform default you’ll want to trace to its billing console.

Resolution Checklist

• Read the response body first. curl -i https://api.example.com/endpoint and look at what the 402 actually says — it names the reason far more often than people expect.
• Identify who sent it: your own hosting/commerce platform (site owner) or a third-party API you call (developer). That single distinction picks your next move.
• If it’s a metered API, check your plan usage and billing dashboard. Upgrade, top up credits, or wait for the reset window. Do not change your request — it isn’t the problem.
• If it’s your own platform, check every paid service’s billing status: hosting, commerce platform, and metered dependencies. Clear the overdue balance and the 402 lifts.
• If the body carries a payment challenge (L402, x402, a Lightning invoice), you’ve hit a paywall handshake. Follow its flow: pay, capture the proof or token, retry the request with it attached.
• Only after ruling all of that out should you suspect a misconfiguration — a gateway mapping some other condition onto 402 by mistake. That’s rare, and it’s the last thing to check, not the first.

When to Escalate

• If you’ve paid, topped up, or cleared the balance and 402 persists past the provider’s stated propagation time, it’s a billing-system issue on their side. Contact the provider with the invoice or account ID — you can’t fix a stuck billing state from the client.
• If you’re integrating a payment-native API (x402, L402) and the retry-with-proof step keeps returning 402, the problem is in how you’re presenting the payment token, not in the payment itself. Capture the full request and response and check the token format against their docs.
• If a 402 shows up on an endpoint that was never meant to be paid — no quota, no subscription, no billing relationship — then something in the path is misusing the code. Trace which hop injects it; a proxy or gateway mapping an unrelated failure onto 402 is a configuration bug worth fixing at the source.