trace-debug

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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]]).
- `REQUEST_TIMEOUT` → the CLI stopped waiting; the API was reached. Raise
  `--timeout` (default 120000ms, above the API's own 90s 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]].

From ZenRows/cli, MIT.

More from ZenRows/cli