HTTP 402 Payment Required – Free, Online, Private

What HTTP 402 means

402 was reserved for future payment flows and never grew a general HTTP authentication scheme the way 401 did. Servers use it anyway when a subscription has lapsed or a quota that money would raise has been hit. Because there is no standard challenge header, the body has to carry the explanation. Clients cannot handle 402 generically.

402 Payment Required belongs to the 4xx client error class. Clients that only look at the class will group it with its neighbors. Clients that care about the exact code should use the narrower rule on this page, because the class is only the first digit.

When you see HTTP 402

When you see HTTP 402 Payment Required, stop on that exact status line. 402 Payment Required is reserved for payment, and it is rarely given a standard body. The trace that usually produces it: A subscription lapsed and the API refused the call. The 4xx client error class only tells you the first digit. A neighbor in that class is a different fault, and the fix on this page does not transfer to it.

Return 402 if your API's contract says a billable account is required and the account is not in good standing. Document the body. If the user is simply over a free rate limit, 429 is often clearer. If they are not allowed regardless of payment, use 403. Do not use 402 as a joke.

How to fix HTTP 402

To fix HTTP 402, change the condition that made the server choose Payment Required. Do not retry until the billing state changes. Show the message. Retrying spends nothing and fixes nothing. Retry after the user pays, not on a timer. The status will not clear itself. If the log line is a different code, leave this page. The mix-up people make with 402 is this one: 429 is a rate limit and often includes Retry-After. 403 is a refusal that payment will not cure. 401 is missing credentials.

• A client treated 402 as a transient 429 and retried all night.
• The body did not say which account or which plan failed.
• A paywall used 402 for a browser navigation where a 303 to a pricing page would have been more useful.

An access log that only stores 402 is not enough to tell these apart. Keep the method, the path, and a request id. Do not keep the Authorization header or a request body that might be a token. The status explains the outcome. It is not a place to echo secrets back to the client either.

Example response

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

{"error":"subscription inactive"}

There is no WWW-Authenticate equivalent that every client understands. Say what is unpaid and what the client can do. A link to the billing page belongs in the body or in a Link header you document.

What the client should do

Do not retry until the billing state changes. Show the message. Retrying spends nothing and fixes nothing.

Do not cache 402 as the resource. The account may become active. A stored 402 would keep a paying user blocked.

Retry after the user pays, not on a timer. The status will not clear itself.

Codes people confuse with HTTP 402

429 is a rate limit and often includes Retry-After. 403 is a refusal that payment will not cure. 401 is missing credentials.