402 Payment Required
Reserved for future use. In practice, APIs use it to signal a billing problem such as an exhausted quota or an unpaid invoice.
Status
HTTP/1.1 402 Payment Required
Details
- Category: 4xx
- Status: Standard. Registered with IANA and defined by a current standards-track RFC.
- Specification: RFC 9110 §15.5.3
- Cacheable: Only with explicit cache headers
- Response body: Allowed
- Retry: Retry only after changing the request
402 has been reserved since the original HTTP/1.1 spec, with no standard semantics ever defined. There is no interoperable meaning to rely on, and no standard way to express what payment is expected.
That has not stopped anyone. Several large APIs return 402 when a subscription lapses, a credit balance runs out, or a plan limit is exceeded, with the details in the body. Treat it as a vendor-specific billing signal and read the documentation for the API you are calling.
Common causes
- A subscription expired or a payment failed.
- A prepaid credit balance reached zero.
- A plan quota was exhausted and the provider chose 402 rather than 429.
How to fix it
As the client
- Read the body for the specific billing condition. There is no protocol-level meaning to infer.
- Stop retrying. No amount of retrying settles an invoice, and aggressive retries on 402 often trigger rate limits on top.
As the server
- Document exactly what 402 means in your API, because the client cannot know otherwise.
- Include the account state and a link to resolve it in the error body.
Examples
POST /api/v2/order HTTP/1.1
Host: api.example.com
Authorization: Bearer sk_live_example
HTTP/1.1 402 Payment Required
Content-Type: application/json; charset=utf-8
{"error":"balance_exhausted","balance":0,"billing_url":"/dashboard/billing"}