Is 402 actually used?

It was reserved for future use for decades, but plan-limited APIs have made it genuinely common.

What should a 402 body contain?

What limit was hit, what the current plan allows, and where to change it.

HTTP 402 Payment Required

Reserved in the original spec and now used in practice for quota, billing and insufficient-funds conditions.

Defined in RFC 9110 §15.5.3 — 402 Payment Required · MDN reference

Where you meet HTTP 402 in production

Rare in public APIs and increasingly common in SaaS ones: an exhausted quota, an unpaid invoice, a feature behind a plan the caller is not on.

Why you would test it

Rare enough that most clients have never seen one, which is exactly why it is worth provoking before a payment provider sends you one in production.

What your client should do about a 402

Never retry. A 402 is resolved by a human doing something commercial, not by the client trying again. Surface the message and the upgrade path; a retry loop here just burns quota that is already exhausted.

402 versus the codes it gets confused with

402 vs 403 Forbidden — 403 is a permissions decision. 402 is a billing one — the same account with the same role would succeed on a different plan.
402 vs 429 Too Many Requests — 429 is "too fast, slow down". 402 is "you have used your allowance for the period".

Endpoints that return 402

6 endpoints in this playground answer with 402. Every one is free, needs no signup, and can be called from the browser or with curl.

POST https://funapi.dev/api/bank/v1/transfers — Insufficient funds (Bank API) Open & run this endpoint
GET https://funapi.dev/api/bank/v1/premium/statements — Always. Payment Required on demand, like the pizza oven’s 500. (Bank API) Open & run this endpoint
GET https://funapi.dev/api/fiba/v1/players/{id}/advanced — Payment Required (FIBA World Cup API) Open & run this endpoint
POST https://funapi.dev/api/gta/v1/vehicles/{id}/respray — Not enough cash (GTA API) Open & run this endpoint
POST https://funapi.dev/api/gta/v1/weapons/{id}/buy — Not enough cash (GTA API) Open & run this endpoint
DELETE https://funapi.dev/api/gta/v1/wanted — Not enough cash (GTA API) Open & run this endpoint

Questions about HTTP 402

Is 402 actually used?: It was reserved for future use for decades, but plan-limited APIs have made it genuinely common.
What should a 402 body contain?: What limit was hit, what the current plan allows, and where to change it.

Other client error codes

All HTTP status codes · All 39 mock REST APIs · Getting started guide

Last updated 6 September 2026