HTTP 402 Payment Required — What It Means & How to Debug

HTTP 402 Payment Required is reserved for future use and indicates the requested resource requires payment — used by some APIs for paywalled endpoints.

What It Means

The HTTP 402 Payment Required status code is one of the most intriguing codes in the HTTP specification. It was defined in the original HTTP/1.1 RFC (RFC 2068) but left “reserved for future use.” Unlike every other standard status code, 402 has no defined behavior — it exists as a placeholder for a future digital payment or micropayment system that never materialized at the protocol level.

In practice, some APIs and services have adopted 402 to signal that the requested resource requires payment, a subscription upgrade, or a quota top-up. It is not an official use — the HTTP specification has never defined the semantics of 402 — but it has become a de facto convention for paywalled API endpoints.

The key distinction from 403 Forbidden is intent: 403 means the server understands the request but the client lacks authorization (which may or may not be obtainable). 402 specifically signals that the barrier is financial — the resource exists, the client could access it, but payment is required first.

When It’s Sent

• Quota exhausted — a free-tier API user has reached their monthly request limit and must upgrade to continue
• Paywalled content — an API endpoint requires a paid subscription to access premium data
• Trial expired — a free trial period has ended and the client must purchase a plan
• Feature gating — a specific feature requires a higher-tier plan (e.g., “Pro” vs “Free”)
• Prepaid credits depleted — a service that uses per-request credits has run out

Real Example

curl -v -H "Authorization: Bearer free-tier-token" \
  https://api.example.com/premium/data

Expected response:

> GET /premium/data HTTP/1.1
> Host: api.example.com
> Authorization: Bearer free-tier-token
>
< HTTP/1.1 402 Payment Required
< Content-Type: application/json
< Content-Length: 98
<
{"error":"payment_required","message":"Upgrade to Pro for $29/mo to access premium data","plan_url":"https://example.com/upgrade"}

The response body typically includes information about the required plan, pricing, and a link where the client (or user) can complete the payment.

How to Debug

Client-Side

1. Check the response body — look for message, error, or plan_url fields explaining what payment is needed
2. Review your API plan — verify your current subscription tier and its limits
3. Check usage/quotas — many APIs provide a headers like X-RateLimit-Remaining or a separate usage endpoint
4. Upgrade or add payment method — follow the links in the response to complete the purchase
5. Handle gracefully — display a user-friendly message about the paywall instead of a raw error

Server-Side

1. Verify the subscription status — check the database for the user’s current plan and expiration
2. Check current usage — compare against plan limits (rate limits, storage, API calls, etc.)
3. Review trial logic — ensure trial expiration dates are calculated correctly
4. Test with different account tiers — create test accounts for each plan level
5. Monitor payment failures — check for declined credit cards or expired subscriptions

curl

curl -s -w "\nHTTP Code: %{http_code}\n" \
  -H "Authorization: Bearer $(cat token.txt)" \
  https://api.example.com/premium/report

If the response is 402, inspect the response body for the specific payment or quota error. Try with a different token that has an active subscription.

Common Causes

FAQ

Related Codes

• HTTP 403 Forbidden — the server refuses access, which may also be used for paywalled content
• HTTP 429 Too Many Requests — rate limit exceeded, which may trigger after quota is exhausted
• HTTP 401 Unauthorized — the client must authenticate first, often before checking payment status
• HTTP 200 OK — the success response after payment is verified