Skip to content
4024xx · Client errorThe client seems to have erred. RFC 9110 §15.5

HTTP 402 Payment Required: meaning and what to do

Meaning

HTTP 402 Payment Required is reserved by HTTP and used by APIs or proxies for paid access and quota refusals. Read the body and identify the layer.

HTTP 402 means “Payment Required”, but HTTP does not define a payment exchange behind it. RFC 9110 section 15.5.3 reserves the code for future use. IANA lists the registered phrase as Payment Required and cites RFC 9110; that registry entry does not define a payment protocol. Real APIs use 402 for an exhausted plan, a missing payment method or a product that requires a paid entitlement. The response body and documentation carry the service-specific meaning.

A proxy can relay a 402 from the target. It can also send 402 for its own account quota. In an HTTPS request, a proxy that requires payment before opening a CONNECT tunnel returns 402 before TLS starts. curl then reports a tunnel failure and no HTTP status for the target. That distinction tells you whether to inspect the target API or the proxy account.

Reproduce a paid-plan response locally

This Python 3.15.0 server answers a pretend plan endpoint with a machine-readable body. It is a local reproduction of the wire shape, not a claim about a provider’s billing policy:

from http.server import BaseHTTPRequestHandler, HTTPServer
import json

class H(BaseHTTPRequestHandler):
    def do_GET(self):
        body = json.dumps({
            "error": "payment_required",
            "detail": "This plan has no requests left."
        }).encode()
        self.send_response(402)
        self.send_header("Content-Type", "application/json")
        self.send_header("Content-Length", str(len(body)))
        self.end_headers()
        self.wfile.write(body)

HTTPServer(("127.0.0.1", 8540), H).serve_forever()
$ curl -sS -i http://127.0.0.1:8540/pay
HTTP/1.0 402 Payment Required
Server: BaseHTTP Python/3.15.0
Content-Type: application/json
Content-Length: 75

{"error": "payment_required", "detail": "This plan has no requests left."}

curl 8.7.1 with -f exits 22 and prints “The requested URL returned error: 402”. A requests 2.32.3 client exposes 402 Payment Required. Those are client behaviours, not additional protocol semantics.

When 402 appears at a proxy

The saved local proxy capture used curl 8.7.1 against an HTTP CONNECT listener that answered 402. curl printed curl: (56) CONNECT tunnel failed, response 402 and http_connect=402 http_code=000. The zero target code is expected because the TLS request never reached the target.

For a normal HTTP URL, the proxy may return 402 directly and the client can read its body. For HTTPS, inspect http_connect separately from http_code. A response from the origin has a successful CONNECT followed by an HTTP status inside the tunnel. A proxy account refusal has a 402 CONNECT response and no target handshake.

Treat the body as an error contract only when the service documents it. Log the status, Retry-After if present, a request ID and the responding layer. Never place a card number or secret token in a URL while trying to “pay” for a request.

Causes and fixes

Where it appears What it usually means What to change
Origin API response The account lacks a paid entitlement or the plan quota is exhausted Read the provider’s billing response, check the account, and follow its documented upgrade or quota path
HTTP proxy response before CONNECT The proxy account or route requires payment Check the proxy account and credentials; do not keep retrying the same tunnel
HTTPS CONNECT returns 402 The proxy refused before TLS, so the target did not answer Record http_connect=402, then test the proxy account separately from the target
Body says “payment” but service is free A gateway or WAF chose 402 for a local policy Identify the signer with Server, Via and the request ID, then ask that operator
402 after a retry loop Retries cannot create an entitlement or add quota Stop the loop and surface a billing or configuration error to the caller

Do not classify every 402 as transient. A new proxy exit changes neither an origin account nor the proxy subscription. A useful scraper policy is to stop, save the response body, and route the event to account handling. The curl proxy guide shows how to capture CONNECT status, and bandwidth billing explains why a provider may stop a route when an account limit is reached.

The numeric code is therefore only the start of the diagnosis. Save the response body without exposing payment details, record whether the status arrived before or after CONNECT, and follow the service’s account or quota documentation. A client that treats 402 as a transport retry will keep failing while the underlying entitlement remains unchanged.

Frequently asked questions

Is 402 a standard payment protocol?
No. HTTP reserves the number but defines no currency, checkout flow or authentication scheme.
Should a scraper retry 402?
Only after the account state changes. Retrying unchanged is not a network recovery strategy.

Sources

  1. RFC 9110 section 15.5.3: 402 Payment Required
  2. IANA HTTP Status Code Registry

All terms, A to Z