Payment Required

Overview

402 Payment Required was reserved for future use and has no officially standardized meaning in HTTP. Even so, some APIs and SaaS products use it pragmatically to signal that payment or a credit top-up is needed.

It is adopted for "you must pay to continue" situations — exhausted free-tier quota, insufficient credits, an expired subscription. Since there is no standardized header convention, the specifics are usually placed in the response body.

When it happens

• It is returned by paid APIs when free credits or a monthly quota are used up and a higher plan is required.
• Some services return it when a subscription has expired or the account is unpaid and a protected feature is accessed.

Request / Response example

POST /api/v1/generate HTTP/1.1
Host: api.example.com
Authorization: Bearer sk_live_...

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

{"error":"quota_exceeded","message":"Free tier limit reached","upgrade_url":"/billing"}

In code

app.use('/api', (req, res, next) => {
  if (account.creditsLeft <= 0)
    return res.status(402).json({ error: 'quota_exceeded', upgrade_url: '/billing' });
  next();
});

Notes

• Because its meaning is not fixed by the standard, interpretation varies per service, so clients should follow the guidance in the response body (payment URL, remaining credits).
• Pure request-volume throttling is better expressed with 429 Too Many Requests, and lack of permission with 403.
• Payment APIs like Stripe are a notable example of using 402 to indicate a declined card or failed charge.

Related status codes

Related headers

Specification