402 Payment Required: A Reserved Status Code
Original Intent
When HTTP was being developed, there was a vision that the web would support microtransactions — small payments for content, API calls, or services. The 402 status code was reserved to signal that the requested resource requires payment before it can be accessed.
The idea was that a server could respond with 402 and include information about the required payment amount, currency, and payment methods. The client would then handle the payment and retry the request.
Why It Never Took Off
- Lack of standardisation – no standard format was defined for the payment information.
- Security concerns – handling payments directly in HTTP headers is risky.
- Better alternatives – payment gateways, redirects to checkout pages, and subscription models are more practical.
- No browser support – browsers never implemented automatic payment handling for 402.
- Content is mostly free – the web evolved to be ad‑supported rather than pay‑per‑view.
Current Status
Today, 402 is listed in the IANA HTTP Status Code Registry as "reserved". Some experimental systems (e.g., some blockchain-based micropayment protocols) have toyed with it, but no major service uses it. If you encounter a 402 in the wild, it's likely a custom implementation or a joke (like the well‑known 418 I'm a teapot).
Most APIs use:
- 200 OK with a payment link or status information.
- 303 See Other to redirect to a payment page.
- 422 Unprocessable Entity for payment validation errors.
- 409 Conflict for payment conflicts (e.g., insufficient funds).
Should You Use 402?
No. Unless you are working on an experimental payment protocol, avoid 402. It's not supported by browsers or standard HTTP clients, and it will likely confuse your users and developers. Use conventional payment flows instead.
Frequently Asked Questions
Can I use 402 for my own payment system?
Technically you can, but it's not recommended. No standard tooling supports it, and it will be confusing for developers. Stick to standard approaches like redirecting to a payment page.
Has 402 ever been used?
There have been a few experimental implementations (e.g., some early e‑commerce prototypes, blockchain‑based micropayments), but it has never seen widespread adoption.
Is 402 a client error or a server error?
It's classified as a client error (4xx), because it indicates that the client's request cannot be fulfilled until payment is made. The error is on the client side (they haven't paid), not the server.