Errors

Every failure returns the same JSON shape with a standard HTTP status, so there is one thing to parse whatever went wrong.

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "url must be a valid URL"
  },
  "meta": {
    "requestId": "019e8a3c-9f0b-7c12-88ab-1d2e3f4a5b6c"
  }
}

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

Status	Code	What happened	What to do
400	`VALIDATION_ERROR`	The request did not pass validation, for example a missing `url`, `json` without `jsonOptions`, or a `location.country` we do not read from	Fix the request. Sending it again unchanged will fail again.
401	`UNAUTHORIZED`	The key is missing, wrong, revoked or expired	Check the key. See Authentication.
402	`INSUFFICIENT_CREDITS`	Your workspace has no credits left for this call	Top up or upgrade, then retry.
403	`FORBIDDEN`	The key is locked to IP addresses and the call came from another one	Call from an allowed address, or add this one. See API keys.
403	`WORKSPACE_BANNED`	The workspace has been suspended	Contact support.
404	`NOT_FOUND`	The job id does not exist, a `cacheOnly` scrape had no copy, or the page itself says it does not exist	For `cacheOnly`, fetch live instead. For a missing page, check the URL.
422	`UPSTREAM_UNREACHABLE`	The site did not answer, or we could not read that page	Do not retry before `retryAfterSeconds`. See below.
422	`INVALID_INPUT`	The page is too large or too slow to process safely	Try a smaller page or a more specific URL.
429	`TOO_MANY_REQUESTS`	Your workspace went over its per-minute request limit	Wait for `Retry-After`, then retry. See below.
503	`SERVICE_UNAVAILABLE`	Something needed for this call is busy or down on our side	Retry after a short wait, or after `retryAfterSeconds` when given.
504	`REQUEST_TIMEOUT`	The work ran past its 5 minute limit	Retry once later. See below.
500	`INTERNAL_SERVER_ERROR`	An unexpected error on our side	Retry with backoff. If it keeps happening, contact support with the `requestId`.

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.

{
  "success": false,
  "error": {
    "code": "UPSTREAM_UNREACHABLE",
    "message": "We could not read this page, and asking again within 6 hours will not change that.",
    "details": { "retryable": false, "retryAfterSeconds": 21600 }
  },
  "meta": { "requestId": "019e8a3c-9f0b-7c12-88ab-1d2e3f4a5b6c" }
}

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:

Header	Example	Means
`RateLimit`	`"workspace";r=0;t=17`	Requests remaining (`r`) and seconds until the window resets (`t`)
`RateLimit-Policy`	`"workspace";q=600;w=60`	Your plan’s quota (`q`) and the window it covers (`w`), in seconds
`Retry-After`	`17`	On a `429`, the seconds to wait before retrying

Wait for Retry-After instead of a fixed delay.

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.

Get started

Core concepts

Web Scraping

Web Extraction

Data indexes

Codes

A page we cannot read

Rate limits

Timeouts

Errors inside a job

Next: Brand data