What is a 402 error in web scraping?

A 402 “Payment Required” error in web scraping signals your API credits are exhausted or your subscription needs renewal. While technically a reserved HTTP status code for future payment systems, web scraping APIs commonly use 402 to indicate you’ve hit your plan’s request limit. Resolve it by upgrading your plan, purchasing additional credits, or waiting for your billing cycle to reset.

The 402 status code, officially labeled “Payment Required,” is a nonstandard HTTP response code that web scraping services use to indicate payment or credit issues. When a scraping API returns 402, the service cannot process your request because your account lacks sufficient credits, your subscription expired, or you exceeded your plan’s usage limits. Unlike a 200 success code, which confirms request completion, 402 specifically blocks access until payment issues resolve.

Web scraping platforms adopted 402 for practical credit management despite the code’s experimental status. When you make API requests beyond your plan’s allocation, the service returns 402 instead of processing the scrape. The response typically includes details about your remaining credits, upgrade options, or when your quota resets.

Popular scraping services implement 402 for different triggers. Some return it when you exhaust monthly request quotas, others use it for concurrent request limits, and some apply it when specific premium features require plan upgrades. The response body usually contains structured information explaining the exact limitation and how to proceed.

Payment APIs like Stripe also use 402 for failed transactions, expired cards, or declined payments. This creates consistency across payment-related services, where 402 universally signals “payment needed to continue.”

The distinction matters for automation. A 402 error tells your scraper to pause and check billing, potentially auto-upgrading or alerting your team about exhausted credits. A 403 error indicates fundamental access problems like IP blocking, invalid API keys, or requesting forbidden resources, requiring different troubleshooting.

Some services incorrectly use 403 for credit exhaustion, forcing scrapers to parse error messages to understand the real issue. Services properly implementing 402 make automation easier because code can programmatically distinguish payment issues from permission problems.

Monthly request limits generate 402 errors when scrapers exceed allocated requests. If your plan includes 10,000 requests per month and you hit 10,001, the API returns 402 for all subsequent requests until the billing period resets or you purchase additional credits.

Concurrent request limits trigger 402 when too many simultaneous requests execute. Even with available monthly credits, exceeding concurrent connection limits produces 402 responses until active requests complete. This prevents resource abuse while maintaining clear payment-related signaling.

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

Scrapers should catch 402 responses and pause operations rather than retry immediately. Unlike transient network errors that benefit from retries, 402 errors persist until account status changes. Implement exponential backoff or stop scraping entirely to avoid wasting requests against a payment barrier.

Error handling should extract response body details. Most scraping APIs return JSON explaining the limitation, remaining credits, and resolution steps. Parse this information to log specific details rather than generic “402 error” messages. This helps diagnose whether you need more credits, should upgrade plans, or simply wait for quota reset.

Automated monitoring prevents surprise 402 errors. Track your credit usage proactively and set alerts at 80% consumption. This gives time to purchase credits before exhaustion interrupts scraping jobs. Many APIs provide credit usage endpoints specifically for this monitoring.

The 402 “Payment Required” error in web scraping indicates exhausted credits, expired subscriptions, or exceeded usage limits. While technically a reserved HTTP code for future payment systems, scraping APIs adopted it for practical credit management. The error blocks requests until you add credits, upgrade plans, or wait for quota resets.

402 differs from 403 by indicating resolvable payment issues rather than permanent access denial. This distinction enables better automation since code can differentiate between billing problems and authorization failures. Common triggers include monthly request limits, concurrent connection limits, and premium feature access attempts.

Proper error handling requires pausing operations rather than retrying, parsing response details for specific limitation information, and implementing proactive credit monitoring. This prevents wasted requests and service interruptions from unexpected credit exhaustion.

Learn more: MDN Web Docs on 402 Payment Required