402 Payment Required
Reserved for future use in the original specification, and now used in practice by APIs to signal that a plan limit or unpaid invoice is blocking the request.
At a glance
- Status code
- 402 Payment Required
- Class
- 4xx, client error, the request itself is the problem
- Defined in
- RFC 9110
- Cacheable by default
- by explicit headers only
- Response body
- Should explain what needs paying and how.
In detail
There is no standard semantics behind 402. Each API that uses it defines its own, which is why the body matters more here than for almost any other code.
Reasonable for quota exhaustion tied to billing. Not a substitute for 429, which is about rate rather than money.
As a client, treat 402 as non-retryable until a human acts. Backing off and retrying will not create a payment.
Examples
HTTP/1.1 402 Payment Required
Content-Type: application/json
{"error":"plan_limit_reached","upgrade_url":"https://example.com/billing"}Things that catch people out
- Because it is non-standard, generic client libraries often lump 402 into a retry loop with other 4xx codes. Document it loudly.
- Returning 402 for a temporary overage that clears at midnight will train clients to ignore it.
Try it: HTTP Request Builder
Build a request with any method, headers and body, send it, and read the status line the server returns.
HTTP Request Builder
LOCAL · Browser-OnlyBuild and test HTTP requests with custom headers and body
Authentication
Headers
Generate Code
curl -X GET 'https://api.example.com/endpoint' \
-H 'Content-Type: application/json'Showing a sample URL. Enter your endpoint above to update the snippet.
Related HTTP status codes
All http status codes →403 Forbidden
The server understood the request and refuses to fulfil it. Unlike 401, sending different credentials will not help.
429 Too Many Requests
The client has sent too many requests in a given period. The Retry-After header says how long to wait before trying again.
451 Unavailable For Legal Reasons
Access is denied because of a legal demand, such as a court order or a government blocking request.
404 Not Found
The server has no representation for this URL and will not say whether it ever did. The most common status code on the web after 200.
405 Method Not Allowed
The URL exists but does not support the method you used. The Allow header lists the methods it does support.
406 Not Acceptable
The server cannot produce a representation that matches the Accept headers the client sent.
Tools for this
- HTTP Request Builder Free online HTTP request builder - build and test HTTP requests with custom headers and body
- HTTP Headers Checker Free online HTTP headers checker - view HTTP response headers for any URL