Scraping API
Help center

Errors and how to handle them

Every error code the API returns, what it means, and whether to retry.

Errors come back as JSON with a stable code and a human-readable message:

JSON
{ "code": "INSUFFICIENT_CREDITS", "message": "You do not have enough credits to perform this action" }

Codes

HTTP and codeMeaningDo
202 TASK_STILL_PROCESSINGNot an error: the task is not finished yet. GET /task/{id} while it runs, or a POST /task / POST /map that ran past ten minutes. The body carries the task id.Poll GET /task/{id}, or resend the POST with the same Idempotency-Key.
400 INVALID_REQUEST_BODYThe body is not JSON or a top-level field has the wrong type.Fix the request.
400 UNSUPPORTED_TASK_TYPEUnknown type, or a type the route does not take (crawl on /task, map on /job).Use the right route.
400 INVALID_ATTRIBUTESattributes do not parse or fail validation, for example an object where a string is expected (extract_selector), a js_instructions step that is not a single-action object or names an unknown action, an unknown block_resource value, a SERP device other than desktop or mobile, a negative SERP page, or a model on an engine other than duck_ai or a model duck.ai does not offer.Check the request against the reference. Do not retry unchanged.
400 MISSING_TARGET, JOB_REQUIRES_MULTIPLE_TARGETSNo url / prompt / query, or a job with fewer than two targets.Add the target, or send one target to POST /task.
400 INVALID_TASK_ID, INVALID_JOB_ID, INVALID_CURSORThe id or cursor in the URL is malformed.Check the value.
400 INVALID_PROXY_TYPE, INVALID_COUNTRYUnknown proxy plan, or a country on GET /config/proxy/asn that is not a two-letter code.Use Basic or Premium and an ISO 3166-1 alpha-2 code.
400 INVALID_IDEMPOTENCY_KEYIdempotency-Key empty, longer than 255 characters or sent twice.Send one key of 1 to 255 characters.
400 INVALID_QUERY_PARAMA list call got a limit or page that is negative or not a number, or a job_id that is not a UUID.Fix the query string.
400 INVALID_DATE_FORMAT, INVALID_DATE_RANGE, INVALID_INTERVALA start_date / end_date not in YYYY-MM-DD, an end before the start (analytics: a range over 365 days), or an unknown analytics interval.Fix the dates or pick hourly, daily, weekly or monthly.
400 URL_LENGTH_CANNOT_BE_ZEROPOST /filter/check got no usable URL: the list is empty or every entry is invalid or not http(s).Send at least one http(s) URL.
400 INVALID_CRAWL_PATTERN, CRAWL_UNSUPPORTED_OPTIONA crawl include_paths / exclude_paths entry is not valid RE2, or result_use_ai was set on a crawl.Fix the crawl options.
401 UNAUTHORIZEDMissing or invalid API key.Check the header and whether the key was rotated.
402 INSUFFICIENT_CREDITSNot enough credits for this request.Top up, or lower max_pages on a crawl.
403 FORBIDDENThe account behind the key is deactivated.Contact support.
404 TASK_NOT_FOUND, JOB_NOT_FOUND, CRAWL_NOT_FOUNDNot found. Also returned for ids that belong to another account.Check the id.
409 JOB_NOT_CANCELLABLEThe job or crawl already finished.Nothing to cancel.
409 TASK_ALREADY_EXISTS, JOB_ALREADY_EXISTSThe create collided with an existing task or job and is not an idempotent replay. Nothing charged.Retry the request.
422 IDEMPOTENCY_KEY_REUSEDSame Idempotency-Key sent with a different request.Use a new key. See Retry safely with idempotency keys.
429 CONCURRENCY_LIMIT_REACHEDYou already run as many tasks as your plan allows. Nothing charged.Wait for Retry-After (1 second, sent on every route) and retry.
503 MODULE_UNAVAILABLE, ENGINE_UNAVAILABLEThe task type or AI engine was switched off by an operator; the reason is in message. Nothing charged.Do not retry in a loop. Pick another engine or wait, and check GET /api/v1/config/capabilities.
503 SERVICE_UNAVAILABLEThe API could not check your key because a backing store is down. The key was not rejected and nothing ran or was charged. No Retry-After header.Retry with backoff.
503 API_KEY_RESET_FAILEDThe key could not be rotated; the old key still works.Retry the reset.
500 INTERNAL_ERRORSomething broke on our side.Retry once, then contact support with the timestamp.
500 ANALYTICS_FETCH_FAILEDGET /task/analytics/dashboard could not read the usage data. Your tasks and balance are not affected.Retry after a moment.

Failures that are not HTTP errors

A task can answer 200 and still have status: failed. The fetch ran, the target did not cooperate. Read blocked, status_code and error in the result:

  • blocked: true means the target refused the request. The task is refunded. Retry with js_rendering: true or a Premium proxy.
  • blocked: false with status: failed is usually a timeout or a proxy error. Retry once with a new Idempotency-Key. If it fails again, switch engine or proxy plan.

Read the result envelope covers every field.

Timeouts on your side

POST /task and POST /map hold the connection until the result is ready, for up to ten minutes. Set your client timeout to 120 seconds or more; browser and AI workloads can take longer. If the API answers 202 TASK_STILL_PROCESSING, poll GET /task/{id} with the id from the body. If the connection drops, resend with the same Idempotency-Key to pick up the running task instead of starting a new one.

Repeated 5xx or timeouts from the API itself

If the API, not a target site, keeps answering 5xx or timing out, check status.datafuel.ai before retrying in a loop. GET /api/v1/healthz?deep=1 answers 503 while a dependency is down. Neither needs a key. See Service status and health.