What does a 402 error mean in web scraping?

The 402 status code, officially called "Payment Required," is a nonstandard HTTP response that scraping services use to communicate payment or credit problems. When a scraping API responds with 402, the service is refusing to process your request because your account has no remaining credits, your subscription has expired, or you've gone over your plan's usage threshold. Unlike a 200 success code that confirms the request was fulfilled, 402 specifically prevents access until the payment issue is resolved.

How scraping APIs use 402 errors

Web scraping platforms adopted 402 for practical credit management despite its experimental classification. When you fire API requests beyond your plan's allocation, the service sends back 402 rather than carrying out the scrape. The response body typically includes details about your remaining credits, upgrade paths, or the date your quota resets.

Various scraping services trigger 402 in different situations. Some return it when you exhaust monthly request quotas, others when you breach concurrent request limits, and others when you attempt to access premium features without the right subscription tier. The response body usually carries structured data explaining what limit was hit and what you can do about it.

Payment processors like Stripe also use 402 for failed transactions, expired cards, or declined charges. This creates a coherent pattern across payment-related services where 402 consistently means "you need to pay to continue."

402 versus 403 in API contexts

Status Code	Meaning	Can Be Resolved	Common Use
402 Payment Required	Credits depleted or payment needed	Yes, by paying or upgrading	API rate limits, subscription services
403 Forbidden	Access permanently denied	No, authorization required	Permission issues, IP bans

The difference matters for automation. A 402 error tells your scraper to pause and check billing, possibly triggering an auto-upgrade or alerting your team. A 403 error points to deeper access problems like IP blocking, invalid API keys, or forbidden resources, requiring a completely different troubleshooting approach.

Some APIs mistakenly use 403 for credit exhaustion, forcing scrapers to interpret error messages to identify the real cause. Services that properly implement 402 make automation simpler because code can programmatically tell apart billing problems from permission failures.

Common 402 triggers in scraping

Monthly request limits produce 402 errors once scrapers exhaust their allocated requests. If your plan covers 10,000 requests per month and you attempt request 10,001, the API will return 402 on all following requests until the billing cycle resets or you buy additional credits.

Concurrent request limits trigger 402 when too many simultaneous requests are running. Even if you have monthly credits remaining, surpassing the parallel connection cap generates 402 responses until active requests finish. This prevents resource abuse while keeping payment-related signaling clear.

Premium feature access returns 402 when free-tier users request capabilities reserved for paid plans. Attempting JavaScript rendering, residential proxies, or AI extraction without the appropriate subscription tier generates 402 along with upgrade prompts.

Handling 402 errors in scraper code

Scrapers should catch 402 responses and stop retrying immediately. Unlike intermittent network failures that benefit from retries, 402 errors persist until account status changes. Use exponential backoff or halt scraping entirely to avoid burning requests against a payment wall.

Error handling should extract details from the response body. Most scraping APIs return JSON describing the specific limit hit, remaining credits, and resolution steps. Parse this data to log meaningful information rather than generic "402 error" messages. This helps pinpoint whether you need more credits, a plan upgrade, or simply need to wait for quota renewal.

Proactive monitoring prevents unexpected 402 errors. Track your credit usage continuously and configure alerts at 80% consumption. This gives you time to purchase credits before exhaustion disrupts ongoing scraping jobs. Many APIs expose credit usage endpoints specifically to support this type of monitoring.

Key takeaways

The 402 "Payment Required" error in web scraping signals exhausted credits, an expired subscription, or exceeded usage limits. While technically a reserved HTTP code for future payment systems, scraping APIs adopted it for credit management. The error blocks further requests until you add credits, upgrade your plan, or wait for quota renewal.

402 differs from 403 by pointing to a fixable payment issue rather than a permanent access denial. This distinction improves automation because code can differentiate between billing problems and authorization failures. Common causes include monthly request limits, concurrent connection caps, and attempts to access premium features.

Proper error handling means pausing operations instead of retrying, parsing the response body for specific limit information, and implementing proactive credit monitoring to prevent unexpected service interruptions.