402 Payment Required

What 402 Payment Required means

402 Payment Required was reserved decades ago for some envisioned digital-payment system that never materialized in mainstream HTTP. In 2026, with the rise of agent-payable APIs and credit-based pricing, 402 is finally seeing real usage: services like TerminalFeed return 402 when an authenticated caller has run out of credits or has not yet purchased any. The response should include details on how to add funds.

When servers should return it: Return 402 when authentication succeeded but the caller has insufficient credits, expired billing, or unpaid balance. Include a Link header or response body pointing to the top-up endpoint.

Common causes

• Account balance is zero
• Subscription expired
• Trial period ended
• Per-call credit cost exceeds remaining balance

How to fix 402 Payment Required

• Top up credits via the payment endpoint
• Renew subscription
• Check current balance: curl -H "Authorization: Bearer $TOKEN" /api/payment/balance

Example response

curl -i -H "Authorization: Bearer $TOKEN" https://api.example.com/expensive-call

HTTP/2 402
content-type: application/json
link: <https://api.example.com/payment/info>; rel="payment"
{"error":"insufficient_credits","balance":0,"required":2,"top_up":"/api/payment/buy-credits"}

Related status codes

More references

For a one-page reference of all HTTP status codes, see the HTTP cheat sheet. For testing API responses, try the API Tester tool. For inspecting responses on the command line, the curl cheat sheet covers the most common flags.