Payment Required

4xx Client Error

ELI5

Some APIs use this reserved code to indicate payment is needed, but there's no universal standard — check the API docs to learn what it means for this service.

Server perspective

Treat 402 as a nonstandard, reserved status that some products use for billing or subscription gates.

When to use

•Use 402 only when your API contract explicitly documents that convention
•Prefer more established product contracts when broad interoperability matters
•API requires payment or subscription
•Premium features behind paywall
•Usage quota requires billing
•Subscription expired

How to respond

•Explain the billing condition clearly in the response body
•Document whether the client should upgrade a plan, add funds, or resolve an invoice

Headers to consider

•No status-specific header is required; still send normal HTTP metadata such as Content-Type, caching, or tracing headers when they help the client.

Response body

•Include product-specific billing details because 402 does not have a universal standard workflow

Server-side pitfalls

•Do not assume generic clients or browsers attach special meaning to 402
•Do not use 402 as if it were a widely interoperable standards-based replacement for 403
•Standard authorization (use 403 Forbidden)
•Authentication required (use 401 Unauthorized)
•Standards-focused APIs where interoperability matters

Examples

Premium API feature

Request:GET https://api.example.test/api/premium/analytics

Response:

402 Payment Required

# Headers
Content-Type: application/json

# Body
{
  "error": "payment_required"
}

Analytics feature requires paid subscription

References

Related Status Codes

403

Forbidden

I know who you are, but you're not allowed to do this. You don't have permission for this action.

429

Too Many Requests

Slow down! You're making too many requests too quickly. Wait a bit and try again later.