# 402 Payment Required

> https://http-status.org/docs/402

**Family:** 4xx Client Error

## Rationale

Reserved for future use and nonstandard in practice; some APIs still use it for billing-related restrictions.

## In Plain Terms

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.

## Description

The HTTP 402 Payment Required status code is reserved for future use. The original intention was that this code might be used as part of some form of digital cash or micropayment scheme, but this has not happened, and this code is not usually used.

## Server Perspective

### Usage
- 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

### Implementation
- Explain the billing condition clearly in the response body
- Document whether the client should upgrade a plan, add funds, or resolve an invoice

### Common Headers
- No status-specific header is required; still send normal HTTP metadata such as Content-Type, caching, or tracing headers when they help the client.

### Body
- Include product-specific billing details because 402 does not have a universal standard workflow

### 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

## Client Perspective

### Pitfalls
- Do not assume 402 is standardized the way 401, 403, or 404 are

## Examples

### Premium API feature

Analytics feature requires paid subscription

**Request:**
```
GET https://api.example.test/api/premium/analytics
```

**Response:**
```
402 Payment Required
Content-Type: application/json

{
  "error": "payment_required"
}
```

## Related Codes

- [403 Forbidden](/docs/403.md)
- [429 Too Many Requests](/docs/429.md)