Qaynaq LABS · TOOLS

HTTP · 4xx Client Error

402 Payment Required

Request rejected due to missing or insufficient payment.

When you see this status

  • API requires payment for access
  • Subscription quota exceeded
  • Token balance insufficient
  • Paywall triggered on resource

Common causes

  • Missing payment token
  • Expired payment method
  • Insufficient funds
  • Unpaid invoice

How to debug it

  1. Verify payment token validity
  2. Check account balance
  3. Review subscription status
  4. Inspect payment gateway logs

Return this code in your framework

Express (Node.js)
res.status(402).send('Payment required');
FastAPI (Python)
return JSONResponse(status_code=402, content={'detail': 'Payment required'})
NestJS
@Get() @HttpCode(402) async paywall() { return { message: 'Payment required' }; }
Go (net/http)
w.WriteHeader(http.StatusPaymentRequired); w.Write([]byte("Payment required"))

About HTTP 402

HTTP status code 402 Payment Required is part of the 4xx Client Error family. Request rejected due to missing or insufficient payment. Understanding it is essential for backend engineers, API designers, and anyone debugging integrations between services.

The Qaynaq Labs HTTP Status Code Explainer covers all standard codes with practical guidance: what triggers them, how to debug them in production, and exactly how to return them from common frameworks. Each code page is hand-curated and verified.

Frequently asked

Can I use 402 for free trials?

No. 402 implies a payment requirement, not trial access. Use 200 or 403 for trials.

Is 402 widely implemented?

No. 402 is reserved but rarely used in practice. Most APIs use 403 or custom codes.

Should 402 include a Retry-After header?

Yes. Include Retry-After with timestamp or delay for payment retry guidance.