When a Web Scraper API request fails, the response includes an HTTP status and a JSON body with an error code and a message:
{
"error": {
"code": "insufficient_credit",
"message": "Not enough credit for this call."
}
}
Use the “code” to identify the error, not the “message”, which can change. Keep in mind that requests ending in an error don’t use credits.
Errors You Need to Fix Before Retrying
If you retry a request that returns one of these errors without changing anything, you’ll get the same error again.
Error | What it means | What to do |
400 invalid_request | The request isn’t valid. The message names the problem. | Fix the request body as described in the message |
401 invalid_token | The API token is missing or not recognized | Check your token, or generate a new one in the dashboard |
402 insufficient_credit | Your credit balance is zero | Purchase more credits |
403 account_suspended / account_disabled | Your account is suspended or disabled | Contact IPRoyal Support |
404 not_found | No image was found at the URL, or the endpoint doesn’t exist | Check the image URL or the endpoint address |
413 payload_too_large | The request body is larger than 100 KB | Send only the documented fields |
422 no_data_extracted | ‘Parse’ was on, but the page had no structured data | Send the request again with ‘Parse’ option disabled |
Temporary Errors You Can Retry
These errors are usually temporary, so you can retry the request. Wait a little longer before each new attempt, for example, 2 seconds, then 4, then 8, and add a short random delay to each wait. If the error continues after a few attempts, stop and try again later.
Error | What it means |
429 concurrency_limit_exceeded | Too many of your scrape requests are running at the same time |
500 / 503 internal_error | A temporary problem on IPRoyal’s side |
502 upstream_unavailable | The scrape couldn’t be completed |
503 capacity_exceeded | The whole service is at full capacity, regardless of your own limit |
When the Target Blocks the Request
A ‘422 blocked’ error means the target website stopped your request. Retrying right away rarely works, so wait a while before trying again, or send the request with a different ‘geo_location’ value.
Note: IPRoyal already retries some temporary failures once before it responds.
Errors from the Target Website
If the target website itself returns an error, such as a 404 page, Web Scraper API doesn’t treat it as an API error. The request returns HTTP 200, and the target’s status appears in the ‘status_code’ value of the result.
Check the ‘status_code’ value before you use the content, so you don’t save an error page as real data.
Learn more about each error code in our Web Scraper API documentation.