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 11, 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
- -Billing account in test mode receives live payment token, and payment gateway blocks charge attempt.
- -Subscription renewal webhook failed, leaving account past due so premium API methods are gated by billing.
- -Usage-based plan exhausted prepaid credits, and metering service requires top-up before serving more requests.
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
- -classify a normalized
billing_gate_reasonfield in error telemetry to distinguish payment failures from plan-entitlement failures at scale.
Decision Support
Compare Guide
401 Unauthorized vs 403 Forbidden: Auth vs Access Denied
Fix 401 Unauthorized vs 403 Forbidden by separating authentication failures from authorization denials, then apply the right login or permission fix fast.
Playbook
Auth Incident Playbook (401 / UNAUTHENTICATED)
Use this playbook to separate missing, expired, or invalid identity proof from authorization and transport failures, and apply credential-source-correct fixes safely.
Official References
Provider Context
This guidance is specific to HTTP services. Always validate implementation details against official provider documentation before deploying to production.