Skip to content
ENPT

HTTP status code · Client errors (4xx)

402 Payment Required

402 Payment Required is officially "reserved for future use", so no standard defines what a client should do with it. In practice you see it when an API or platform refuses service because of billing: a declined card, an unpaid invoice or a plan limit.

Facts about this status code
Class4xx, Client errors
Defined inRFC 9110 §15.5.3
Cacheable by defaultOnly with explicit Cache-Control or Expires
Safe to retryAfter the payment or billing problem is resolved
Relevant headersNone specific to this code
StatusDeprecated: Reserved for future use by RFC 9110; there is no standard behavior.

What 402 means

The code has been reserved since HTTP/1.1 was drafted in the 1990s, when micropayments for web content were expected to arrive soon. RFC 9110, section 15.5.3, still says only that it is reserved, and browsers do nothing special when they get one.

Vendors adopted it anyway. The Stripe API returns 402 "Request Failed" when parameters were valid but the operation failed, for example a declined card. The Shopify API returns 402 when a shop is frozen for an unpaid balance. The x402 protocol, published by Coinbase in 2025, uses 402 responses that carry payment instructions so software clients can pay per request.

Common causes

If you are visiting the site

  • Your subscription lapsed or the card on file was declined, and the service paused your account.
  • You reached the quota of a free or paid plan (API calls, exports, seats).

If you run the server

  • A payment API call failed for a business reason, such as Stripe reporting a card decline with 402.
  • Your application maps "plan limit reached" or "account suspended for non-payment" to 402.

How to fix it

If you are visiting the site

  • Open the billing page of the service, update the payment method or settle the open invoice.
  • Upgrade the plan or wait for the quota to reset if the message mentions a limit.

If you run the server

  • When you consume a payment API, read the error body (Stripe includes a decline_code) instead of branching on the status alone.
  • If you send 402 yourself, put a machine-readable reason and a link to the billing page in the body; clients have no standard way to interpret the code.
  • Consider 403 with a clear message instead, if your clients or proxies treat unknown usage of 402 poorly.

How to send 402

Express (Node.js)
app.post('/exports', (req, res) => {
  res.status(402).json({ error: 'Monthly export limit reached', billing_url: '/settings/billing' });
});
Next.js App Router route handler
// app/exports/route.ts
export async function POST() {
  return Response.json(
    { error: 'Monthly export limit reached', billing_url: '/settings/billing' },
    { status: 402 }
  );
}
Go net/http
mux.HandleFunc("POST /exports", func(w http.ResponseWriter, r *http.Request) {
	w.Header().Set("Content-Type", "application/json")
	w.WriteHeader(http.StatusPaymentRequired) // 402
	w.Write([]byte(`{"error":"Monthly export limit reached","billing_url":"/settings/billing"}`))
})
Python FastAPI
from fastapi import FastAPI
from fastapi.responses import JSONResponse

app = FastAPI()

@app.post("/exports")
def create_export():
    return JSONResponse(status_code=402, content={"error": "Monthly export limit reached", "billing_url": "/settings/billing"})

Commonly confused with

402 vs 403
403 is a general refusal with a standard meaning; 402 narrows the reason to payment but has no standardized client behavior.
402 vs 429
429 is a rate limit that clears with time; a 402 plan limit clears only after paying or upgrading.

Frequently asked questions

Is 402 Payment Required an official status code?
It is registered, but RFC 9110 marks it as reserved for future use and defines no semantics. Any meaning comes from the API that sends it.
Why does Stripe return 402?
Stripe uses 402 "Request Failed" when the request was valid but could not complete, most often a card decline. The error object in the body says why, including a decline_code for card failures.
Should my SaaS API use 402 for an expired subscription?
Many do, and it is a clear signal to developers. Include the reason and a billing link in the body, because generic HTTP clients treat 402 like any other 4xx error.

Last reviewed by Arielton Oberek.