Errors

HTTP status codes, the standard JSON error shape, and fixes for the issues developers hit most often.

Error Codes

Code	Message	Description
400	Bad Request	Missing or invalid parameters
401	Unauthorized	Invalid or missing API key
403	Forbidden	Account cancelled or insufficient credits
404	Not Found	Run ID not found or not owned by user
429	Too Many Requests	Rate limit exceeded or duplicate request
500	Internal Server Error	Server error, please retry
503	Service Unavailable	Scraper at capacity, try again later

Error Response Format

All error responses follow a consistent JSON format with an error message.

{
  "error": "Invalid or missing API key"
}

// For capacity errors
{
  "error": "capacity",
  "reset": "2025-09-22T15:00:00Z",
  "message": "Scraper at global capacity. Please try again after 3:00 PM"
}

Common Issues & Solutions

Apollo - No Cancellation Available

Apollo scrapes cannot be cancelled once started. Ensure your request parameters are correct before submitting.

Apollo - Filters 1.0 Required

Only Filters 1.0 URLs with [] notation are supported. URLs without [] parameters will be rejected.

Maps - Search Terms Required

Maps scraper requires searchStringsArray parameter: ["coffee shop", "cafe"]. At least one search method must be provided.

Amazon - categoryUrls Required

Amazon scraper requires categoryUrls as array of objects: [{"url": "https://amazon.com/..."}]. The keywords parameter alone will not work.

Results Expired

Download results within 48 hours. Set up webhooks for automatic download.

Insufficient Credits

Check wallet balance with /api/v1/wallet endpoint before large scrapes.