Working with it
Errors
Every code, what it means, what to do.
A failure is always the same shape, so you can branch on error.code and never parse a message:
{ "success": false, "error": { "code": "BLOCKED", "message": "Target returned a challenge at every attempt", "detail": { "status_code": 403 } }}
Error codes
| Code | HTTP | What to do |
|---|---|---|
INVALID_REQUEST | 400 | The body did not validate. The message names the field. Fix and retry. |
UNAUTHORIZED | 401 | Missing, mistyped or revoked key. Check the Authorization header. |
ROBOTS_DENIED | 403 | The site's robots rules disallow it. Retrying will not change that. |
JOB_NOT_FOUND | 404 | Unknown job id, or one that has aged out. |
RATE_LIMITED | 429 | Slow down, or raise the plan. Back off and retry. |
TARGET_ERROR | 502 | The site itself answered with an error; the real status is in detail.status_code. Usually the URL. |
FETCH_FAILED | 502 | The site could not be reached at all — DNS, TLS, refused connection. Worth one retry. |
BLOCKED | 502 | The site refused every attempt. Retrying immediately rarely helps; try again later or from another country with location. |
TIMEOUT | 504 | The page took longer than your timeout. Raise it, or drop waitFor. |
EXTRACTION_FAILED | 500 | The page came back but nothing usable could be read from it. Try another format. |
INSUFFICIENT_CREDITS | 402 | The balance is empty. Nothing was fetched and nothing was charged. Top up or wait for the monthly refresh. |
FORBIDDEN_SCOPE | 403 | The key is valid but does not hold the scope this endpoint needs. Grant it in API keys. |
ENGINE_REFUSED | 503 | That site is being given a rest after repeated failures. Try again later, or try a different site. |
SEARCH_UNAVAILABLE | 503 | No search provider is configured on this deployment. Nothing is broken; search is simply not switched on here. |
PLACES_UNAVAILABLE | 503 | Places is not part of this deployment. |
PLATFORMS_UNAVAILABLE | 503 | Platform shortcuts are not part of this deployment. |
PROXY_UNAVAILABLE | 503 | No proxy provider is configured, so a proxied fetch cannot be served. |
COMPANY_UNAVAILABLE | 503 | Company enrichment is not part of this deployment. |
INTERNAL | 500 | Ours, not yours. It is logged with a trace id; send it to us. |
Retries
Retry FETCH_FAILED, TIMEOUT and RATE_LIMITED with a widening gap. Do not retry INVALID_REQUEST, UNAUTHORIZED or ROBOTS_DENIED — the same request will fail the same way.
A failure costs nothing. None of these count against your allowance, so a retry loop cannot quietly drain it.