HTTP 402 Payment Required

HTTP 402 Payment Required was reserved in the original HTTP specification for future use in electronic payment systems. That payment infrastructure never materialized as a standard HTTP mechanism, so 402 has no formally standardized semantics. In practice, modern APIs use it informally to mean: the requested action requires payment — a subscription upgrade, additional credits, or a paid plan — before it can be fulfilled. It is the closest thing HTTP has to a “you need to pay for this” error code.

HTTP 402 quick reference →

Quick reference

Code	402
Name	Payment Required
Category	4xx Client Error
Specification	RFC 9110 §15.5.3
IANA status	Reserved for future use — no standardized semantics
Cacheable?	No

The original intent

RFC 2068 and RFC 2616 (the original HTTP/1.1 specifications) included 402 with a note that it was “reserved for future use.” The HTTP working group anticipated a future where micropayment protocols would be standardized and integrated into HTTP — where servers could request payment for resources and clients would automatically handle payment transactions. The Digital Commerce drafts and early electronic commerce protocols from the 1990s (such as Millicent and various SET-based systems) were the context.

That future never came to pass as a standardized HTTP mechanism. Electronic commerce evolved through out-of-band payment systems (payment gateways, subscription management platforms) rather than HTTP-level payment negotiation. RFC 9110 retains the code as reserved but provides no semantic definition beyond its historical context.

How APIs use 402 today

Despite the lack of standardization, several prominent APIs use 402 to indicate payment-related access failures. This informal convention has become de facto for APIs with usage-based billing or subscription tiers:

API credit or quota exhaustion:

POST /api/v1/completions HTTP/1.1

HTTP/1.1 402 Payment Required
Content-Type: application/json

{"error": {
  "code": "insufficient_credits",
  "message": "Your credit balance is insufficient for this request.",
  "credits_required": 10,
  "credits_available": 3,
  "top_up_url": "https://platform.example.com/billing/credits"
}}

Plan limit exceeded:

GET /api/reports/advanced-analytics HTTP/1.1

HTTP/1.1 402 Payment Required
{"error": "plan_limit_exceeded",
 "message": "Advanced analytics requires a Pro plan or higher.",
 "current_plan": "starter",
 "upgrade_url": "https://example.com/pricing"}

Subscription expired or payment failed: Some services use 402 when a subscription renewal payment failed, leaving the account in a grace period or suspended state.

402 vs 401 vs 403

Code	Meaning	Resolution
401	Unauthorized	Authenticate first (provide credentials)
402	Payment Required	Pay for access (upgrade plan, add credits)
403	Forbidden	Authentication cannot grant this permission (policy decision)

The distinction matters for client behavior: a 401 triggers an authentication flow, a 402 should trigger a payment or upgrade flow, and a 403 indicates a permanent permission denial that payment would not resolve. APIs that need to distinguish “not authenticated” from “authenticated but not paid” from “paid but not permitted” should use all three codes appropriately.

Best practices for 402 responses

Since 402 has no standardized semantic structure, the response body carries all the meaningful information. A well-designed 402 body should include:

Machine-readable error code: A string the client can switch on ("insufficient_credits", "subscription_expired", "plan_limit_exceeded"). This allows programmatic handling without parsing the human-readable message.

Current state and requirement: What the client currently has versus what is required. For credits: current balance and required amount. For plans: current plan and required plan. This data helps clients display meaningful error states to their users.

Action URL: A link to where the user can take action — the billing portal, upgrade page, or credits purchase page. Providing a direct URL reduces friction for users who need to resolve the payment issue.

Retry guidance: After payment, clarify whether the request can be retried immediately or whether there is a propagation delay (for example, credit balance updates that take a few minutes to apply).

Frequently asked questions

What does HTTP 402 mean?

In the RFC, 402 is reserved with no defined semantics. In practice, APIs use it to mean the request requires payment — a subscription upgrade, additional credits, or a paid plan — before it can be fulfilled. Check the response body for details on what payment is required and how to resolve it.

Is 402 a standard HTTP code?

It is a registered code (IANA lists it as “Payment Required”) but marked as reserved for future use with no defined semantics. There is no standard structure for 402 requests or responses. Its use for subscription/credit errors is an informal convention, not an HTTP standard.

Why not use 403 for payment-gated content?

403 Forbidden implies the client’s credentials are valid but do not grant access, and that this is a permanent permission denial not affected by payment. 402 signals that the access failure is due to payment status and that paying (upgrading, adding credits) will resolve it. Using 402 allows clients and UIs to show appropriate “upgrade your plan” prompts rather than generic “access denied” messages.

What response headers should accompany 402?

No standard headers are defined for 402. The response body should contain all relevant information. Some APIs include custom headers like X-Credits-Remaining or X-Plan-Limit for monitoring, but these are non-standard and should not replace a structured JSON body.

Standards reference

Definitions from the IANA HTTP Status Code Registry and RFC 9110 §15.5.3. Human-readable guidance by ErrorLookup. · HTTP 402 quick reference →