What does HTTP status code 402 mean?
The 402 Payment Required status code is defined by RFC 9110 only as “reserved for future use”. The specification gives it no semantics, so generic clients, proxies and HTTP libraries treat it as an ordinary 4xx. Some APIs, Stripe among them, use it anyway for requests that are valid but fail for payment reasons, such as a declined card.
When to use it in APIs
Use 402 when the request is well-formed and authorized, and a payment would fix it immediately: a declined card, an exhausted prepaid balance, or a subscription that has lapsed for non-payment. Because the status code carries no defined meaning, the response body has to do the work: send a problem type such as insufficient funds that tells the client what failed and how to resolve it.
Do not use 402 for a plan allowance that resets on its own at the end of a billing period. Waiting fixes that, so it is 429 Too Many Requests with Retry-After, as described in quota exceeded.
How it compares to other codes
- 403 Forbidden: The caller is not permitted to do this, and paying will not change that (for example, a role lacks permission). 402 means the caller is permitted but the account cannot cover the cost.
- 429 Too Many Requests: The caller has used up a rate or period allowance and should retry later. 402 means retrying will not help until a payment is made.
