Skip to main content
Every failure returns the same JSON shape with a standard HTTP status, so there is one thing to parse whatever went wrong.
boolean
Always false on an error. A successful response never has this shape.
string
A stable code for the reason. Write your logic against this. The message wording may change; the code will not.
string
A plain explanation, safe to show to a person.
object
Extra context when there is some, such as which field failed validation or retryAfterSeconds.
string
The id of this request. Quote it when you contact support. Every response also carries it in the X-Request-Id header.
Failed calls are free. Credits are only charged when you get a result, so an error never costs anything. See Credits.

Codes

A page we cannot read

422 with UPSTREAM_UNREACHABLE means the site did not respond, or we could not read that page. This is a fact about that URL, not a fault in our service, and asking again straight away will not change it.
When details.retryAfterSeconds is there, asking again before then returns this same answer at once. After that, a new call makes a fresh attempt.

Rate limits

Every response carries headers that tell you where you stand: Wait for Retry-After instead of a fixed delay.

Retrying safely

A network can drop the connection after we finished the work but before you got the answer. Retrying then would run the call again and charge for it again. To retry without that risk, send an Idempotency-Key header on any POST: a unique string of up to 255 visible characters, the same on every retry of that call.
For 12 hours after the first call:
  • A repeat returns the first answer again, with the same status and X-Request-Id, and an Idempotent-Replayed: true header. Nothing runs and nothing is charged.
  • A repeat that arrives while the first call is still running gets 409 with IDEMPOTENCY_IN_PROGRESS and a Retry-After. Send it again after that wait.
  • The same key with a different body gets 409 with IDEMPOTENCY_KEY_REUSED.
  • A call that failed is not remembered, so retrying it with the same key makes a fresh attempt. Failed calls are never charged.
A call that answered 202 with a job replays that same job id, so a retried crawl, batch or long scrape never starts twice. The official SDKs send a key for every POST and reuse it on their own retries.

Timeouts

A call waits for its result for up to 90 seconds, or your timeout. Past that it does not fail: it answers 202 with a job id and keeps working for up to 5 minutes. Only work that runs past those 5 minutes fails, and the job then reports REQUEST_TIMEOUT with status 504. It costs nothing. Pages that hit this are almost always heavily protected. See Jobs & webhooks.

Errors inside a job

A crawl or batch can succeed overall while some of its pages fail. Starting the job and polling it return normal successful responses. Check each entry in the job’s pages for its own status and error, and the job’s status for failed or cancelled.

Next: Brand data

Logos, colours and fonts for any company.