Errors

Reading a failure

A non-200 status from us means we could not complete the work. The body describes what went wrong.

A 200 with disappointing content is a different thing entirely: we fetched the page successfully and the target served something you did not want. Retrying that usually returns the same page. Look at what the target is doing, not at us.

Common causes

Invalid or missing token. Check that token is in the query string on every request, including /balance.

Insufficient balance. Top up under Scraping API → Purchase. Poll /balance between batches so a long run does not stop halfway.

A malformed url. Almost always an unencoded target URL, where the & in the target’s own query string truncated it. See Parameters.

A blocked destination. Some categories are blocked for every account. See Acceptable use; the same policy applies here.

A client timeout that is not our error at all. We may render and retry for tens of seconds. If your client gives up at 10 or 30 seconds, you will see a timeout on work that completed. Set at least 120 seconds.

Retrying

We already retry internally before answering, so a failure that reaches you has usually been attempted several times. Your own retries should be few and spaced out: two attempts with a backoff, not ten in a loop.

Retrying a bad token, an empty balance or a blocked domain never succeeds, and each attempt costs you a round trip. Read the message before retrying.

Getting help

Contact support with the timestamp, the exact url you sent, and the module if you set one. Those make the request findable on our side.