Skip to content

402 Payment Required

Description

The 402 Payment Required status code indicates that the request cannot be processed until the client makes a payment. This status code was initially created for digital payment systems and electronic cash, but is reserved for future use. Despite its "reserved" status, it is sometimes used by services to indicate that a payment is required to access a resource or service.

This status code is commonly used when: - A user has reached the limit of their free tier and needs to upgrade - A subscription has expired and needs to be renewed - A service requires payment before processing a specific request - A resource is only available to paying customers - A trial period has ended

While not as standardized as other HTTP status codes, the 402 Payment Required status provides a clear indication that payment is needed to proceed.

Syntax

The server responds with a 402 Payment Required status:

HTTP/1.1 402 Payment Required
Content-Type: application/json
Content-Length: [length in bytes]

{
  "error": "Payment Required",
  "message": "This request requires payment to proceed"
}

Examples

Subscription Expired Example

A client attempts to access a service with an expired subscription:

Client Request: 

GET /api/premium-data HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Server Response: 

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

{
  "error": "Payment Required",
  "message": "Your subscription has expired",
  "subscription_ended": "2023-05-15T00:00:00Z",
  "renewal_url": "https://api.example.com/billing/renew",
  "plans": [
    {"name": "Basic", "price": "$9.99/month"},
    {"name": "Pro", "price": "$29.99/month"}
  ]
}

API Usage Limit Example

A client exceeds their free tier usage limit:

Client Request: 

GET /api/geocode?address=1600+Pennsylvania+Ave+Washington+DC HTTP/1.1
Host: maps.example.com
API-Key: free_tier_key_123

Server Response: 

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

{
  "error": "Payment Required",
  "message": "You have reached the limit of 100 requests per day on the free tier",
  "usage": {
    "limit": 100,
    "used": 100,
    "reset": "2023-06-16T00:00:00Z"
  },
  "upgrade_url": "https://maps.example.com/pricing",
  "paid_plans_start_at": "$10/month for 10,000 requests"
}

Premium Content Example

A client attempts to access premium content:

Client Request: 

GET /articles/premium/investment-strategies-2023 HTTP/1.1
Host: financial-news.example.org
Cookie: session=user_session_token_789

Server Response: 

HTTP/1.1 402 Payment Required
Content-Type: text/html
Content-Length: 458

<!DOCTYPE html>
<html>
<head>
  <title>Payment Required</title>
</head>
<body>
  <h1>Premium Content</h1>
  <p>This article is available exclusively to our premium subscribers.</p>
  <h2>Subscribe to continue reading</h2>
  <p>Get access to all our premium content and exclusive analysis for just $5.99/month.</p>
  <a href="/subscribe" class="button">Subscribe Now</a>
  <p>Already a subscriber? <a href="/login">Log in</a> to access this content.</p>
</body>
</html>

Summary

The 402 Payment Required status code, while technically reserved for future use, has found practical applications in modern web services to indicate that payment is needed to access a resource or service. It provides a clear signal to clients that financial transaction is required to proceed, making it useful for subscription-based services, freemium models, and paid content platforms. By including information about pricing, subscription options, and payment methods, servers can guide users toward completing the necessary payment to gain access to the requested resource.