Trace & debug

Every fetch/extract writes a trace under .zenrows/runs/<run-id>/ and .zenrows/traces/<run-id>/ (secret-free).

Commands

zenrows trace inspect <run-id>    # raw run record
zenrows trace explain <run-id>    # what happened + likely cause + next action + exact command
zenrows trace replay <run-id>     # reconstruct the command line
zenrows trace export <run-id>     # JSON for sharing

Failure → action map

• FETCH_FAILED / empty content → first retry in auto mode (mode=auto), which escalates for you and bills only for what succeeds. Only when auto mode has failed on its own, take manual control with --manual --js-render, then --premium-proxy. For slow pages, add --wait-for <selector> to a --manual --js-render run; auto mode may ignore it. Each step multiplies the cost of the request, and both together are the most expensive configuration available ([[cost-control]]).
• FETCH_FAILED "The Zenrows API answered HTTP 502/503/504 after N retries" → the CLI already retried a busy answer (--retries). Wait a minute and run the same command again; do not escalate, a costlier configuration does not fix it. A 429 ("Rate limited") keeps its advice with or without --retries: wait a few seconds and retry; if it persists, lower concurrency.
• REQUEST_TIMEOUT → the CLI stopped waiting; the API was reached. Raise --timeout (default 200000ms, above the API's own 180s budget), or drop --wait-for so the request finishes inside that budget and the API returns its own error. Not a connectivity problem — do not chase the network.
• BACKEND_UNAVAILABLE → a genuine transport failure (DNS/TCP/TLS). Check connectivity and zenrows config show.
• AUTH_INVALID → re-check the key, zenrows login --api-key ….
• KEY_CREDIT_CAP_REACHED → this API key hit one of its own credit caps (HTTP 402, gateway code AUTH014, Batch api_key_cap_reached). The account still has credits and its other keys keep working. Do not retry and do not escalate: zenrows usage shows the cap and when it resets. Wait for the reset, or have the account owner raise or remove the cap at https://app.zenrows.com/settings/api-keys.
• POLICY_MAX_CREDITS_EXCEEDED → the account itself is out of credits (or a local policy credit limit was hit). Do not retry-loop; zenrows usage shows when credits renew. Top up or upgrade, or claim the account if it is an auto-created Free plan.
• BATCH_FAILED → the batch run ended failed for a reason other than credits, subscription or key cap (those get POLICY_MAX_CREDITS_EXCEEDED, AUTH_INVALID or KEY_CREDIT_CAP_REACHED, with the run's failure_reason as server_code and its job_id); failure_detail in zenrows batch status <id> --json says why. Once fixed, run the unfinished tasks with zenrows batch rerun <id> --status failed,pending,processing; do not resubmit. Also a 400 (fix the flagged tasks) or a 5xx (retry).
• BATCH_QUOTA_EXCEEDED → 429: 3 active jobs (shared with Crawl), 5 scheduled jobs, or an open job's task cap. Nothing was created; free a slot (see zenrows batch list and zenrows crawl list).
• BATCH_ACCESS_DENIED / BATCH_NOT_FOUND → 403 Batch not enabled, or 404 wrong or deleted job id. Do not retry.
• BATCH_RUN_IN_PROGRESS, BATCH_RUN_ENDED, BATCH_NO_MATCHING_TASKS, BATCH_RERUN_WINDOW_EXPIRED, BATCH_REQUEST_IN_FLIGHT, BATCH_CONFLICT, BATCH_TASK_NOT_READY, BATCH_TASK_FAILED, BATCH_RESULT_EXPIRED → the Batch API's 409/410/422 answers; server_code names the case and next_action the fix. See [[batch-jobs]].
• CRAWL_NOT_ENABLED → the API answered 403 REQS008: Crawl is not enabled for this account. Do not retry; ask Zenrows support for access.
• CRAWL_INSUFFICIENT_CREDITS / CRAWL_KEY_CAP_REACHED → Crawl's 402: the account is out of credits, or this key reached its credit cap (AUTH014). The same codes come back for a crawl that credits ended (stopped, or failed on older deployments; server_code insufficient_credits / api_key_cap_reached); its fetched pages stay readable. Same advice as POLICY_MAX_CREDITS_EXCEEDED / KEY_CREDIT_CAP_REACHED.
• CRAWL_TOO_MANY_CRAWLS → 429 too_many_crawls: the account has reached its limit of active jobs (3 by default), shared with its Batch jobs. Nothing was created; retry after retry_after seconds (see zenrows crawl list).
• CRAWL_FAILED → the crawl ended failed, or stopped with an error other than credits; error.code in zenrows crawl get <id> --json says why, with error.detail. See [[crawl]].
• PARAM_CONFLICT_AUTO_MANUAL → drop the managed flags or add --manual.
• CAPABILITY_UNAVAILABLE → the primitive is not available on this account (e.g. beta/invite-only); use the local-spec path where offered.

Escalate only with evidence from the trace. See [[cost-control]].