402 - Payment Required
HTTP 402 Payment Required is reserved for future use in the standard and is usually provider-specific in practice.
Last reviewed: February 12, 2026|Editorial standard: source-backed technical guidance
What Does Payment Required Mean?
This response usually indicates a provider-defined billing or entitlement gate, so the request remains blocked until commercial/account prerequisites are satisfied.
Common Causes
- -Provider uses custom 402 semantics for billing enforcement.
- -Subscription or entitlement does not permit requested feature.
- -Payment method or account credit state blocks operation.
How to Fix Payment Required
- 1Read provider-specific error payload fields to determine whether issue is billing, quota, or entitlement gating.
- 2Resolve payment/account state (invoice, card, subscription tier, credit balance) for the affected tenant/project.
- 3Retest on the same account context after billing/entitlement changes propagate.
Step-by-Step Diagnosis for Payment Required
- 1Capture full response payload and provider error code taxonomy for the 402 event.
- 2Map failing request to account/tenant billing state at the same timestamp.
- 3Validate entitlement plan includes requested feature/resource operation.
- 4Retest with known-good paid/entitled account to isolate environment versus account-specific causes.
Provider Semantics and Entitlement Mapping
- -Interpret provider-specific 402 meanings (example: API uses 402 for premium-feature gate, not generic payment failure).
- -Verify feature entitlement flags at account or project scope (example: advanced export endpoint disabled on free plan).
Billing State and Account Controls
- -Inspect invoice/credit/payment instrument status (example: expired card triggers account hold and 402 responses).
- -Trace propagation delays after billing updates (example: subscription upgrade active in billing UI but not yet reflected in API auth context).
Implementation Examples
curl -i -X GET https://api.example.com/v1/resource
# Response:
# HTTP/1.1 402 Payment Required
# {"error":"Payment Required","code":"402"}const response = await fetch('https://api.example.com/v1/resource', {
method: 'GET',
headers: { 'Accept': 'application/json' }
});
if (response.status === 402) {
console.error('Handle 402 Payment Required');
}import requests
response = requests.get(
'https://api.example.com/v1/resource',
headers={'Accept': 'application/json'}
)
if response.status_code == 402:
print('Handle 402 Payment Required')How to Verify the Fix
- -Repeat the request with corrected account state and confirm 402 is cleared.
- -Validate related paid-feature endpoints also succeed for the same account.
- -Monitor billing-related error metrics to ensure no recurring entitlement drift.
How to Prevent Recurrence
- -Expose preflight billing/entitlement checks in clients before paid operations are attempted.
- -Alert proactively on impending payment failures, expiring instruments, and credit exhaustion.
- -Document provider-specific 402 semantics so support and engineering triage correctly.
Pro Tip
- -persist a normalized `billing_gate_reason` field in error telemetry to distinguish payment failures from plan-entitlement failures at scale.
Decision Support
Compare Guide
403 Forbidden vs 404 Not Found: When to Hide Resources
Use 403 for explicit access denial, or 404 to conceal resource existence when security policy requires reducing endpoint and object enumeration risk.
Compare Guide
404 Not Found vs 410 Gone: Missing vs Permanent Removal
Learn when to return 404 (missing or temporary absence) versus 410 (intentional permanent removal), including redirect and cache implications.
Playbook
Resource State Playbook (404 / 410 / ResourceNotFound)
Use this playbook to separate temporary missing-resource lookups from permanent removals, then fix scope, lifecycle, and identifier drift safely.
Official References
Provider Context
This guidance is specific to HTTP services. Always validate implementation details against official provider documentation before deploying to production.