HTTP 402 Payment Required: letting AI agents pay for your API
Short version: more and more of your API traffic comes from programs (scripts, other apps and AI agents), not people. When they hit something paid, a login page or a generic error tells them nothing. A 402 with a small JSON body (which plan, what price, where to buy) turns “blocked” into “here's how to get access”.
What 402 means
402 Payment Required has been in HTTP since the beginning, but the specification still says it is “reserved for future use” (RFC 9110, §15.5.3). There is no single standard for what a 402 response must contain, so in practice each API defines its own body. That freedom is the point: you can make it useful.
Why it matters now
- Programs can’t click “Upgrade”. A person who hits a paywall sees a pricing page. A script or an AI agent sees an HTTP status and a body. If the body is HTML or a vague error, it fails or retries.
- Agents are increasingly the ones calling APIs. Coding assistants, research agents and automation tools fetch data on someone’s behalf. Some will be able to buy access if you tell them how.
- The alternative is scraping. If the only door is closed and unlabelled, the data gets taken another way. A clear paid door is better for both sides.
402 vs 401 vs 403 vs 429
| Status | Means | What the client should do |
|---|---|---|
| 402 | Access to this resource is sold; you don’t have a valid purchase for it | Buy the plan named in the response, then retry with the key |
| 401 | You are not authenticated | Log in or send credentials |
| 403 | The credential is invalid or revoked | Stop; don’t retry with the same key |
| 429 | Too many requests right now | Wait and retry later |
What a useful 402 contains
Enough for a program to act without reading your documentation:
HTTP/1.1 402 Payment Required
Content-Type: application/json
{
"error": "payment_required",
"request_id": "01a1fe84-…",
"payment": {
"plan_id": "api-reports",
"checkout_url": "https://example.com/plans/api-reports",
"currency": "EUR",
"unit_price_minor": 150,
"unit_size": 1000
}
}
plan_id: which plan unlocks this route, so buying the wrong one is avoidable;checkout_url: where to buy it;currency,unit_price_minor(price in cents) andunit_size: what it costs, in a form a program can compare;request_id: so support can trace the exact request.
After buying, the client retries with its key, for example Authorization: Bearer bgat_…. A key for a different plan should get 402 again; an invented or revoked key, 403.
Do it safely
- Never leak secrets in the body. Plan and price are public; keys, internal IDs and other customers' data are not.
- Don't charge the preflight. Browsers send
OPTIONSbefore many cross-origin requests. It must never count as a use or get a 402. - Fail closed. If you can’t check the licence, answer
503on paid routes. Never serve them for free. - Separate agents you welcome from agents you sell to. A search crawler you want indexing your site is different from an agent bulk-downloading your data.
With LicenRoute
LicenRoute’s Express middleware answers exactly that 402 shape on the routes you choose, and its test suite checks every case: no key, valid key, other plan, invented key, quota used up, revoked key and service outage. You set it up from the CLI, or your AI coding assistant does it with your approval.
See the 402 on your own machine
Run the 10-minute tutorial on the example app, or paste the prompt into your assistant. Building something agents should pay for? Tell us.