402

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