Skip to content

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

An exhausted prepaid balance

HTTP request

POST /api/v2/order HTTP/1.1
Host: api.example.com
Authorization: Bearer sk_live_example

HTTP response

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

{"error":"balance_exhausted","balance":0,"billing_url":"/dashboard/billing"}

Specifications

See also