Errors

A failed request returns a non-zero errorId with a code and a human-readable description. Failed requests are never billed.

The error shape

When something goes wrong, the response carries a non-zero errorId, a stable errorCode string to branch on, and an errorDescription for humans. Always branch on errorCode, not on the description text.

error.json

{
  "errorId": 1,
  "errorCode": "ERROR_SCRAPE_BLOCKED",
  "errorDescription": "Target returned a bot-block page. Retry with asp enabled."
}

Error codes

Error code	Description
`ERROR_INVALID_PARAMS`	The url or another parameter is malformed. Fix the request; do not retry as-is.
`ERROR_SCRAPE_FAILED`	Generic fetch failure, for example the crawler could not reach the target. Retry, optionally with retry set.
`ERROR_SCRAPE_BLOCKED`	The target blocked the request, or asp was on but still could not clear it. Enable asp, change proxyCountry, or try a residential session.
`ERROR_NAVIGATION_FAILED`	The rendered page crashed or failed to load. Adjust waitUntil or the jsScenario, then retry.
`ERROR_TIMEOUT`	The synchronous 90-second window elapsed. The taskId in the response is still valid; poll getTaskResult for the result.
`ERROR_KEY_DOES_NOT_EXIST`	The clientKey is unknown. Check the key in your dashboard.
`ERROR_RATE_LIMITED`	Too many requests too fast. Back off and retry.
`ERROR_CONCURRENT_LIMIT`	You have hit your plan's concurrent-request cap. Slow the fan-out or raise the limit.
`ERROR_PROXY_REQUIRED`	The request needs a proxy pool it was not given. Set proxyPool, or enable asp which forces residential.

Failed requests are free

Any request that ends in an error is not charged, so a defensive retry costs you nothing on the failed attempt. See Pricing.

Timeouts are not failures

ERROR_TIMEOUT means the synchronous wait exceeded roughly 90 seconds, not that the scrape failed. The work continues in the background, and the response still includes a taskId. Poll POST https://api.capzy.ai/getTaskResult with that taskId and your clientKey until status is ready. This is the same polling path described in Making a request for the processing response.

When you are blocked

ERROR_SCRAPE_BLOCKED is the one to plan for. If a target starts blocking you, enable asp to auto-bypass its anti-bot layer, and consider setting a proxyCountry closer to the site's audience. See Rendering & anti-bot.

Pricing