PayPerScrape Logo
Documentation

Troubleshooting

Common errors, their causes, and solutions for PayPerScrape API.

Overview

This guide covers the most common errors you might encounter when using PayPerScrape, along with their causes and solutions.

Most errors include helpful error messages and metadata to help diagnose the issue. Always check the response body and headers for additional context.

Common Errors

rate_limit_exceeded429

Too many requests in the time window

Common Causes

  • Exceeding IP-based rate limit (20/min for /api/scrape)
  • Exceeding wallet-based rate limit (10/min for /api/scrape)
  • Exceeding feedback rate limits (5/hour for API, 3/hour for web)

Solutions

  • Check the Retry-After header for when to retry
  • Implement exponential backoff in your client
  • Reduce request frequency
  • For feedback: wait longer between submissions
payload_too_large413

Request body exceeds maximum size

Common Causes

  • Request body larger than 10 KB
  • Including large data in request body

Solutions

  • Reduce request body size to under 10 KB
  • Remove unnecessary fields from request
  • For feedback: keep notes under 300 characters (API) or 1000 characters (web)
BLOCKED_HOST403

Domain is blocked or restricted

Common Causes

  • Attempting to scrape localhost or private network IPs
  • Domain is in the blocked hosts list
  • Invalid or malformed URL

Solutions

  • Use public URLs only (no localhost, 127.0.0.1, or private IPs)
  • Ensure URL is properly formatted (http:// or https://)
  • Check that domain is publicly accessible
invalid_json400

Request body is not valid JSON

Common Causes

  • Malformed JSON syntax
  • Missing Content-Type: application/json header
  • Empty or null request body

Solutions

  • Validate JSON syntax before sending
  • Set Content-Type header to application/json
  • Ensure request body is valid JSON object
incomplete502

Content incomplete after all escalation attempts

Common Causes

  • Content requires login credentials
  • Geographic blocking
  • Anti-bot protection that couldn't be bypassed
  • Site is down or unreachable

Solutions

  • Check metadata.is_partial to see if partial content was returned
  • Review decision_reason in metadata for specific issue
  • Submit feedback if content should be accessible
  • Try again later if site was temporarily unavailable
Domain not scraped403

Cannot submit feedback for domain not recently scraped

Common Causes

  • Domain was not scraped in the last 24 hours (API) or 7 days (web)
  • Wallet address doesn't match recent scrapes

Solutions

  • Scrape the domain first before submitting feedback
  • Ensure wallet address matches the one used for scraping (API feedback)
  • Use web form if domain was scraped more than 24 hours ago
CAPTCHA verification failed403

CAPTCHA token validation failed (web feedback only)

Common Causes

  • Invalid or expired Turnstile token
  • CAPTCHA not completed
  • Token from different domain

Solutions

  • Complete the CAPTCHA challenge
  • Ensure Turnstile token is fresh and valid
  • Retry the submission
Unauthorized401

Invalid x402 payment signature

Common Causes

  • Missing or invalid X-402-Payment header
  • Payment signature verification failed
  • Payment not completed

Solutions

  • Ensure x402 payment is completed before request
  • Include valid X-402-Payment header
  • Check x402 SDK integration

Error Response Format

Standard Error Response

Error Responsejson

Error responses typically include:

  • error - Error code identifier
  • message - Human-readable error message
  • retry_after - Seconds to wait before retrying (for rate limit errors)
  • issues - Validation errors (for 400 Bad Request)

Debugging Tips

  • Check Response Headers: Rate limit headers (X-RateLimit-*) provide detailed information about your current usage
  • Review Metadata: For scraping errors, check the metadata object for decision_reason and attempts array
  • Validate URLs: Ensure URLs are properly formatted and publicly accessible
  • Check Request Size: Keep request bodies under 10 KB
  • Implement Retry Logic: Use exponential backoff when receiving 429 or 502 errors
  • Submit Feedback: If you encounter persistent issues with a domain, submit feedback to help improve strategies

Getting Help

If you continue to experience issues: