402 Payment Required
Reserved for future use. Used by some APIs (like Stripe) indicating charge failures.
Usually happens because:
- ☑ Stripe or payment gateway API
- ☑ SaaS subscription plan credit limits
🔍 Quick Checklist:
Meaning
The HTTP 402 Payment Required client error status code is reserved for future use. The original intention was that this code might be used as part of some form of digital cash or micro-payment scheme, but it is currently used by platforms like Stripe, Shopify, or Google Developers to indicate subscription/charge limits.
Root Causes
- Stripe or payment gateway API request processing charge declines.
- SaaS subscription plan credit limits exceeded.
| Cause | Frequency |
|---|---|
| Stripe or payment gateway API | ⭐⭐⭐⭐⭐ |
| SaaS subscription plan credit limits | ⭐⭐⭐⭐ |
Common Mistakes
- Using 402 for unauthenticated requests (use 401 instead).
- Using 402 in standard public applications before billing modules are integrated.
How to Fix
Framework-Specific Examples
Checking API key transaction limits and returning 402.
app.get('/api/premium', (req, res) => {
if (req.user.hasActivePlan === false) {
res.status(402).json({ error: 'Subscription Required' });
}
});Server Configuration Examples
IP connection throttling mapped to 402 warnings.
# Custom redirection for billing redirectsPrevention
- Validate user subscription statuses before allowing them to run resource-heavy API operations.
Frequently Asked Questions (FAQ)
Q: Is 402 Payment Required part of the official HTTP spec?
Yes. It was defined in the original HTTP/1.1 specifications, but its implementation details were left reserved for future use.
Q: Which major platforms use 402 status codes?
Stripe uses it for card charging failures. Google Developers API uses it when developers exceed daily budget/query limits.
Q: Does 402 trigger native browser popups?
No. Browsers handle 402 exactly like other error codes, passing the response details directly to application scripts.
Q: Should I use 402 in my private API?
Yes. If your application offers premium tiers, returning a 402 status code is a highly semantic way to signal payment or tier upgrades.