Errors and how to handle them

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

Written By Carmine Cella

Last updated About 3 hours ago

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

{ "code": "INSUFFICIENT_CREDITS", "message": "Not enough credits to run this task" }

Codes

HTTPcodeMeaningDo
400INVALID_ATTRIBUTESMalformed body, unknown task type, or attributes that do not match type.Check the request against the reference. Do not retry unchanged.
401UNAUTHORIZEDMissing or invalid X-API-Key.Check the header and whether the key was rotated.
402INSUFFICIENT_CREDITSNot enough credits for this request.Top up, or lower max_pages on a crawl.
404NOT_FOUND, JOB_NOT_FOUNDTask or job not found. Also returned for ids that belong to another account.Check the id.
422IDEMPOTENCY_KEY_REUSEDSame Idempotency-Key sent with a different request.Use a new key. See Retry safely with idempotency keys.
503MODULE_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/capabilities.
500INTERNAL_ERRORSomething broke on our side.Retry once, then contact support with the timestamp.

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. Set your client timeout to 120 seconds or more; browser and AI workloads can take longer. 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.