Error Codes
Every error the API can return and how to handle them.
Error Codes
All errors return a JSON body with an error field. Some include a message field with more detail.
{
"error": "Insufficient credits",
"message": "You need at least 1 scrape credit(s) for a scrape operation."
}Error Reference
| Status | Error | When | What to Do |
|---|---|---|---|
| 400 | A valid URL is required | Missing or invalid url in request body | Check your request body includes a valid URL |
| 401 | Unauthorized | Missing or invalid API key | Check your Authorization: Bearer header |
| 401 | Invalid API key | API key doesn't exist or was revoked | Create a new key at /app/api-keys |
| 402 | Insufficient credits | Not enough credits for the operation | Buy more credits or wait for monthly renewal |
| 403 | Batch scraping not available | Your plan doesn't support batch | Upgrade to Pro or Business plan |
| 403 | API access not available | Your plan doesn't include API access | Upgrade to Starter or above |
| 404 | Scrape not found | Invalid scrape ID or not owned by you | Check the scrape ID is correct |
| 422 | Scrape failed | Target page couldn't be scraped | Try a different URL or adjust options |
| 429 | Concurrent scrape limit reached | Too many active scrapes for your plan | Wait for current scrapes to finish |
| 500 | Internal Server Error | Unexpected server error | Retry after a few seconds |
| 502 | Scraping service unavailable | Internal scraping engine is down | Retry after a few seconds |
Common Errors
402 — Insufficient credits: Check your remaining credits at /app/plan. Credits renew monthly on your billing date.
429 — Concurrent limit: Your plan has a max number of simultaneous scrapes. Wait for one to finish or upgrade for higher limits.
Tips
- Always check the HTTP status code before parsing the response body.
- For
502errors, implement a simple retry with exponential backoff. - If you get
401, verify your API key hasn't been revoked at /app/api-keys.