@zenrows/cli 1.5.5 → 1.6.1

package/README.md

@@ -203,7 +203,12 @@ run out (default 600). When the time runs out, the command exits 0 and prints
 the crawl with status `running` and the hint `zenrows crawl wait <crawl-id>`
 (under `--json`, in `note`); the crawl keeps running. Ctrl-C stops the wait, not the crawl, and exits 130;
 resume with `zenrows crawl wait <crawl-id>`. A crawl that ends `failed` exits 1
-with `CRAWL_FAILED`.
+with `CRAWL_FAILED`. A crawl that ends `stopped` because the account ran out of
+credits or the API key hit a credit cap also exits 1, with the code a refused
+create gets: `CRAWL_INSUFFICIENT_CREDITS` or `CRAWL_KEY_CAP_REACHED`, and the
+API's `insufficient_credits` or `api_key_cap_reached` as `server_code`. Older
+deployments end such a crawl `failed`; it gets the same codes. Its fetched pages
+stay readable.
 
 Errors carry the API's code as `server_code`, `crawl_id` on any call about one
 crawl, and `retry_after` on a 429. When the account has reached its limit of

package/dist/src/cli/commands/crawl.js

@@ -15,7 +15,8 @@ import { assertDomainAllowed, assertWithinLimits, loadPolicy } from "../../core/
 import { newRunId, writeRun } from "../../core/artifacts.js";
 import { contentIdOf, createCrawl, downloadCrawl, getCrawl, getCrawlContent, isTerminal, listAllResults, listCrawls, stopCrawl, waitForCrawl, } from "../../core/crawl-api.js";
 import { asNumber, asString, parse } from "../command.js";
-import { ToolkitError } from "../../core/errors.js";
+import { ToolkitError, isKeyCapReached, keyCapReached, quotaExhausted } from "../../core/errors.js";
+import { readAccount } from "../../core/agent-account.js";
 import { printError, writeOut, writeOutStream } from "../output.js";
 /** The API's default for `max_pages` (and `max_items`) when the flag is unset. */
 const DEFAULT_MAX_PAGES = 100;
@@ -35,8 +36,11 @@ export const crawl = {
         "                                    the local policy max_pages_per_run caps it (default 1000)",
         "    --include-patterns <p>          keep only URLs containing this substring (repeatable)",
         "    --exclude-patterns <p>          drop URLs containing this substring (repeatable)",
-        "    --output-format html            also fetch each kept URL's page HTML (read with content/download);",
-        "                                    each kept page is one more fetch counted by --max-pages",
+        "    --output-format <html|markdown> also fetch each kept URL's page, as HTML or Markdown",
+        "                                    (read with content/download); each kept page is one more",
+        "                                    fetch counted by --max-pages",
+        "    --discovery links               how the crawl finds the URLs it follows; links (the",
+        "                                    default) follows the links in each page's HTML",
         "    --follow                        wait until the crawl ends (Ctrl-C stops the wait, not the crawl)",
         "    --timeout <s>                   with --follow: stop waiting after s seconds (default 600)",
         "    --idempotency-key <key>         so a retried create starts no second crawl",
@@ -44,13 +48,15 @@ export const crawl = {
         "  get <id> [--cursor <c>] [--limit <n>]",
         "                                    the crawl and one page of its results (limit up to 10000)",
         "  list [--cursor <c>] [--limit <n>] your crawls, newest first (limit up to 100)",
-        "  results <id> [--limit <n>]        every kept URL as JSONL; on a running crawl, those kept so far",
-        "                                    (partial). --limit is the page size per request",
+        "  results <id> [--limit <n>]        every kept URL as JSONL; partial while more can come (a running",
+        "                                    crawl, or pages still in flight after a stop). --limit is the page size",
+        "                                    per request",
         "    --out <file>                    write the results to a file instead of printing",
         "  content <id> <content_id>         print one kept URL's page (content_id or content_url)",
         "    --out <file>                    write it to a file instead",
         "  download <id> [--out <file>]      save the NDJSON export (with page HTML for html crawls),",
-        "                                    default <id>.jsonl; partial while the crawl runs",
+        "                                    default <id>.jsonl; partial while more can come (a running",
+        "                                    crawl, or pages still in flight after a stop)",
         "  stop <id>                         stop a running crawl (an ended crawl answers as it ended)",
         "  wait <id> [--timeout <s>]         poll until the crawl ends or s seconds (default 600) run out;",
         "                                    a crawl still running then is printed, not stopped",
@@ -102,6 +108,7 @@ async function createCmd(rest, ctx) {
         "include-patterns": { type: "string", multiple: true },
         "exclude-patterns": { type: "string", multiple: true },
         "output-format": { type: "string" },
+        discovery: { type: "string", multiple: true },
         follow: { type: "boolean" },
         timeout: { type: "string" },
         "idempotency-key": { type: "string" },
@@ -137,16 +144,29 @@ async function createCmd(rest, ctx) {
         params.exclude_patterns = exclude;
     const outputFormat = asString(values["output-format"]);
     if (outputFormat !== undefined) {
-        if (outputFormat !== "html") {
+        if (outputFormat !== "html" && outputFormat !== "markdown") {
             throw new ToolkitError({
                 code: "INVALID_USAGE",
                 message: `Invalid --output-format value '${outputFormat}'.`,
-                likely_cause: "--output-format takes html only. Without it, a crawl returns URLs only.",
-                next_action: "Pass --output-format html, or leave it out.",
+                likely_cause: "--output-format takes html or markdown. Without it, a crawl returns URLs only.",
+                next_action: "Pass --output-format html or --output-format markdown, or leave it out.",
             });
         }
         params.output_format = outputFormat;
     }
+    const discovery = patterns(values.discovery);
+    if (discovery.length) {
+        const other = discovery.find((d) => d !== "links");
+        if (other !== undefined) {
+            throw new ToolkitError({
+                code: "INVALID_USAGE",
+                message: `Invalid --discovery value '${other}'.`,
+                likely_cause: "--discovery takes links. Without it, the crawl follows the links in each page's HTML.",
+                next_action: "Pass --discovery links, or leave it out.",
+            });
+        }
+        params.discovery = ["links"];
+    }
     const timeoutMs = timeoutFlag(values.timeout);
     const idempotencyKey = asString(values["idempotency-key"]);
     assertUsable("crawl");
@@ -269,14 +289,17 @@ async function downloadCmd(rest, ctx) {
     assertUsable("crawl");
     const apiKey = requireApiKey();
     const { status, count } = await downloadCrawl(id, (ndjson) => writeOutStream(file, ndjson), { apiKey });
-    const partial = status === "running";
+    // A stop reads `stopped` at once, but the API still reads the pages in flight for up to 10
+    // minutes and builds the file from what it has kept until then. Its next_cursor says when it is done.
+    const partial = status === "running" || (status === "stopped" && (await listAllResults(id, { apiKey, pageSize: 10_000 })).partial);
+    const note = partial ? downloadNote(status) : undefined;
     if (json) {
-        log.out(JSON.stringify({ ok: true, crawl_id: id, status: status ?? null, partial, count, file }, null, 2));
+        log.out(JSON.stringify({ ok: true, crawl_id: id, status: status ?? null, partial, ...(note ? { note } : {}), count, file }, null, 2));
     }
     else {
         log.success(`Downloaded ${count} result(s) → ${file}`);
-        if (partial)
-            log.warn("  The crawl is still running: this file is partial. Download again once it ends.");
+        if (note)
+            log.warn(`  ${note}`);
     }
     return 0;
 }
@@ -284,9 +307,10 @@ async function downloadCmd(rest, ctx) {
 function printResults(id, status, results, o) {
     if (o.outFile)
         writeOut(o.outFile, toJsonl(results));
+    const note = o.partial ? partialNote(status) : undefined;
     if (o.json) {
         const rows = o.outFile ? { file: o.outFile } : { results };
-        log.out(JSON.stringify({ ok: true, crawl_id: id, status, count: results.length, ...rows, partial: o.partial }, null, 2));
+        log.out(JSON.stringify({ ok: true, crawl_id: id, status, count: results.length, ...rows, partial: o.partial, ...(note ? { note } : {}) }, null, 2));
         return 0;
     }
     if (o.outFile) {
@@ -296,10 +320,20 @@ function printResults(id, status, results, o) {
         log.info(`${results.length} result(s) for crawl ${id} (status: ${status}):`);
         log.out(toJsonl(results).trimEnd());
     }
-    if (o.partial)
-        log.warn("  The crawl is still running: these results are partial. Read them again once it ends.");
+    if (note)
+        log.warn(`  ${note}`);
     return 0;
 }
+function downloadNote(status) {
+    return status === "running"
+        ? "The crawl is still running: this file is partial. Download again once it ends."
+        : "The crawl was stopped, but pages fetched before the stop can still add lines for up to 10 minutes: download again later.";
+}
+function partialNote(status) {
+    return isTerminal(status)
+        ? "The crawl ended, but pages fetched before the end can still add URLs for up to 10 minutes: read the results again later."
+        : "The crawl is still running: these results are partial. Read them again once it ends.";
+}
 async function contentCmd(rest, ctx) {
     const { values, positionals } = parse(rest, { out: { type: "string" }, json: { type: "boolean" } });
     const json = ctx.json || values.json === true;
@@ -382,7 +416,8 @@ async function stopCmd(rest, ctx) {
     assertUsable("crawl");
     const apiKey = requireApiKey();
     const s = await stopCrawl(id, { apiKey });
-    const headline = s.status === "stopped" ? `Stopped crawl ${id}` : `Nothing to stop: crawl ${id} had already ended`;
+    // A crawl stopped on credits carries `error`: it had already ended, this call did not stop it.
+    const headline = s.status === "stopped" && !s.error ? `Stopped crawl ${id}` : `Nothing to stop: crawl ${id} had already ended`;
     return printCrawl(s, ctx.json || values.json === true, headline);
 }
 /**
@@ -404,33 +439,50 @@ async function waitUntilEnd(id, opts) {
     }
 }
 /**
- * The error for a crawl that ended `failed`, or null for any other state. The
- * crawl's own `error.code` picks the next action.
+ * The error for a crawl that ended `failed`, or `stopped` with an `error` (the
+ * account ran out of credits or the API key hit a credit cap), or null for any
+ * other state. A crawl the credits ended gets the code and advice a create
+ * refused with 402 gets (`CRAWL_INSUFFICIENT_CREDITS`, `CRAWL_KEY_CAP_REACHED`),
+ * whether the API reports it `stopped` or, as older deployments do, `failed`.
+ * Any other `error.code` picks the next action of a `CRAWL_FAILED`.
  */
 export function crawlFailure(c) {
-    if (c.status !== "failed")
+    const creditStop = c.status === "stopped" && !!c.error;
+    if (c.status !== "failed" && !creditStop)
         return null;
     const code = c.error?.code;
+    const ids = { server_code: code, crawl_id: c.crawl_id };
+    const where = `crawl ${c.crawl_id}`;
+    const detail = c.error?.detail || undefined;
+    const getCmd = `zenrows crawl get ${c.crawl_id}`;
+    if (code && isKeyCapReached(code)) {
+        const cap = keyCapReached(where, { status: null, detail }).toJSON();
+        return new ToolkitError({ ...cap, ...ids, code: "CRAWL_KEY_CAP_REACHED", suggested_commands: [...(cap.suggested_commands ?? []), getCmd] });
+    }
+    if (code === "insufficient_credits") {
+        const acct = readAccount();
+        const quota = quotaExhausted(where, acct?.unclaimed ? acct.claimUrl : undefined, { status: null, detail }).toJSON();
+        return new ToolkitError({ ...quota, ...ids, code: "CRAWL_INSUFFICIENT_CREDITS", suggested_commands: [...(quota.suggested_commands ?? []), getCmd] });
+    }
     const why = [code, c.error?.detail].filter(Boolean).join(": ");
     const next = {
-        insufficient_credits: "The account ran out of credits. Check `zenrows usage`, add credits, then start a new crawl.",
         seed_unreachable: "The start URL could not be fetched (the site may be blocking it). Check it with `zenrows fetch <url>`.",
         no_items_found: "Nothing matched. Loosen --include-patterns / --exclude-patterns, raise or drop --depth, or check the start page with `zenrows fetch <url>`.",
     };
     return new ToolkitError({
         code: "CRAWL_FAILED",
-        message: `Crawl ${c.crawl_id} failed.`,
+        message: creditStop ? `Crawl ${c.crawl_id} stopped before it finished.` : `Crawl ${c.crawl_id} failed.`,
         likely_cause: why || "The crawl ended in status failed without a reason.",
         next_action: (code && next[code]) || "Read the error, fix the cause, then start a new crawl.",
-        suggested_commands: [`zenrows crawl get ${c.crawl_id}`],
-        server_code: code,
-        crawl_id: c.crawl_id,
+        suggested_commands: [getCmd],
+        ...ids,
     });
 }
 /**
  * Print a crawl (or a stop answer), structured under --json, and return the exit
- * code: 1 when it ended `failed`, else 0. `stopped` is a deliberate outcome, so
- * it exits 0 but prints as a warning. `extra` carries the results a `get` read,
+ * code: 1 when it ended `failed`, or `stopped` because credits ran out or the
+ * API key hit a credit cap, else 0. A `stopped` crawl the caller stopped is a
+ * deliberate outcome, so it exits 0 but prints as a warning. `extra` carries the results a `get` read,
  * or the note of a wait that ran out.
  */
 function printCrawl(c, json, headline, extra = {}) {

package/dist/src/core/batch-api.js

@@ -21,6 +21,7 @@ import { readAccount } from "./agent-account.js";
 import { registerSecret } from "./logger.js";
 import { CLI_USER_AGENT } from "./config.js";
 import { agentClientHeader } from "./agent-client.js";
+import { BILLING_URL } from "./open-url.js";
 /** Confirmed Batch API base (no trailing slash). */
 export const DEFAULT_BATCH_API_BASE = "https://async.api.zenrows.com/v1";
 /** Env var to override the Batch API base (local/staging testing). */
@@ -116,6 +117,17 @@ function problemToError(status, body, method, path) {
             suggested_commands: ["zenrows batch estimate jobs.jsonl"],
         });
     }
+    if (status === 401 && serverCode === "subscription_inactive") {
+        // The key is fine; the subscription needs a billing action. Same
+        // AUTH_INVALID code as any 401 so callers that branch on it keep
+        // working; only the guidance changes, since re-entering the key won't help.
+        return new ToolkitError({
+            code: "AUTH_INVALID",
+            message: "Zenrows refused the Batch API request because the subscription is not active.",
+            likely_cause: `${cause.replace(/\.?$/, ".")} The API key is valid, but the subscription is past due, unpaid, incomplete or paused.`,
+            next_action: `Fix the subscription in Billing (${BILLING_URL}), or in Azure Marketplace if you subscribed there, then retry.`,
+        });
+    }
     if (status === 401) {
         return new ToolkitError({
             code: "AUTH_INVALID",

package/dist/src/core/config.js

@@ -14,7 +14,7 @@ export const CONFIG_VERSION = "0.1.0";
  * entrypoint) so core modules — telemetry, signup provenance — can read it
  * without an import cycle. `VERSION` in `cli/index.ts` re-exports this.
  */
-export const CLI_VERSION = "1.5.5"; // x-release-please-version
+export const CLI_VERSION = "1.6.1"; // x-release-please-version
 /** The User-Agent on every request to a Zenrows API. The gateway reads the version from it. */
 export const CLI_USER_AGENT = `zenrows-cli/${CLI_VERSION}`;
 /** Env var to override the Fetch and Extract API base (local/staging testing). */

package/dist/src/core/crawl-api.js

@@ -10,7 +10,7 @@
  * Crawl SDKs do (see `retryStatuses`). `fetchImpl` / `sleepImpl` are injectable
  * for tests.
  *
- * `output_format` takes `html` only (absent = URLs only). Response fields we do
+ * `output_format` takes `html` or `markdown` (absent = URLs only). Response fields we do
  * not model pass through untouched.
  */
 import { Readable } from "node:stream";
@@ -297,6 +297,8 @@ export function createCrawl(params, opts) {
         body.exclude_patterns = params.exclude_patterns;
     if (params.output_format !== undefined)
         body.output_format = params.output_format;
+    if (params.discovery?.length)
+        body.discovery = params.discovery;
     return crawlJson("POST", "/crawls", {
         ...opts,
         body,
@@ -319,7 +321,7 @@ export function listCrawls(opts) {
 export function stopCrawl(id, opts) {
     return crawlJson("POST", `/crawls/${encodeURIComponent(id)}/stop`, { ...opts, crawlId: id, retryStop: true });
 }
-/** The page of one kept URL (HTML for `output_format: html`). */
+/** The page of one kept URL, in the crawl's `output_format`. */
 export async function getCrawlContent(id, contentId, opts) {
     const res = await crawlFetch("GET", `/crawls/${encodeURIComponent(id)}/contents/${encodeURIComponent(contentId)}`, {
         ...opts,
@@ -390,9 +392,9 @@ export async function listAllResults(id, opts) {
         const rows = page.results ?? [];
         results.push(...rows);
         if (!rows.length || !page.next_cursor || page.next_cursor === cursor) {
-            // Every page was read. An ended crawl keeps no new URLs, even while pages in flight after
-            // a stop keep next_cursor set, so only a running crawl's results are partial.
-            return { crawl: page, results, partial: !isTerminal(page.status) };
+            // Every page was read. The API keeps next_cursor set while URLs can still come: on a
+            // running crawl, and for up to 10 minutes after a stop, from the pages still in flight.
+            return { crawl: page, results, partial: page.next_cursor != null };
         }
         cursor = page.next_cursor;
     }

package/dist/src/core/errors.js

@@ -45,7 +45,9 @@ export class ToolkitError extends Error {
  * (so `claimUrl` is surfaced); for a real logged-in account there is nothing to
  * claim — the step is to add credits / upgrade in the dashboard. `status`/`detail`
  * let the caller record the actual upstream response (402 usage-limit, 429
- * quota, …) instead of a hardcoded status.
+ * quota, …) instead of a hardcoded status. `status: null` is for a crawl the
+ * credits stopped: its status call succeeded, so there is no HTTP error to cite,
+ * only `url` (the crawl).
  */
 export function quotaExhausted(url, claimUrl, opts = {}) {
     // Say that the allowance comes back. Without it this reads as a permanent paywall,
@@ -58,10 +60,11 @@ export function quotaExhausted(url, claimUrl, opts = {}) {
         ? `You are on the Zenrows Free plan. Claim your account to keep your usage and add credits: ${claimUrl}. ${renewLine}`
         : `You are out of Zenrows credits. ${renewLine} To carry on now, add a credit pack (${BILLING_TOPUP_URL} opens the purchase directly) or upgrade your plan: ${PLANS_URL}`;
     const detail = opts.detail ? `${opts.detail.replace(/\.\s*$/, "")}. ` : "";
+    const where = opts.status === null ? `Stopped ${url}` : `HTTP ${opts.status ?? 429} for ${url}`;
     return new ToolkitError({
         code: "POLICY_MAX_CREDITS_EXCEEDED",
         message: "Zenrows request quota exhausted.",
-        likely_cause: `${detail}HTTP ${opts.status ?? 429} for ${url}`,
+        likely_cause: `${detail}${where}`,
         next_action: claimLine,
         suggested_commands: ["zenrows usage"],
     });

package/dist/src/core/open-url.js

@@ -12,6 +12,7 @@ export const DASHBOARD_URL = "https://app.zenrows.com/dashboard";
 /** Lands on Billing with the credit-pack purchase modal already open (app PR #1972). */
 export const BILLING_TOPUP_URL = "https://app.zenrows.com/billing?topup=open";
 export const PLANS_URL = "https://app.zenrows.com/plans";
+export const BILLING_URL = "https://app.zenrows.com/billing";
 export const DOCS_URL = "https://docs.zenrows.com";
 /** Append query params to a URL (used to attach anonymous `utm_*` attribution). */
 export function withParams(url, params) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zenrows/cli",
-  "version": "1.5.5",
+  "version": "1.6.1",
   "description": "Open-source CLI, MCP, skills, templates, workflows, recipes, and evals layer for giving AI agents reliable access to protected web data through Zenrows cloud infrastructure.",
   "type": "module",
   "license": "MIT",

package/skills/crawl/SKILL.md

@@ -11,8 +11,8 @@ Give Crawl one start URL; it follows the links on that page (and on the
 pages behind it, up to the depth you set) and returns the URLs it keeps. Use it
 when you know where the items live (a category page, a blog index, a docs
 section) but not the item URLs themselves. Once you have the URLs, read pages
-with `zenrows fetch` / `zenrows extract`, or ask Crawl for each page's HTML
-with `--output-format html`.
+with `zenrows fetch` / `zenrows extract`, or ask Crawl for each page itself
+with `--output-format html` or `--output-format markdown`.
 
 Crawl stays on the start URL's registrable domain; subdomains count. An account without Crawl access gets
 403 `REQS008` → `CRAWL_NOT_ENABLED` ("Crawl is not enabled for this account");
@@ -50,16 +50,18 @@ zenrows crawl results <id> --out urls.jsonl  # same, as JSONL
   `partial: true`. Read again once the crawl ends. `--limit` sets the page size
   of each request.
 
-## Page HTML
+## Page content
 
 ```
 zenrows crawl create <url> --depth 1 --output-format html --max-pages 20 --follow
+zenrows crawl create <url> --depth 1 --output-format markdown --max-pages 20 --follow
 zenrows crawl results <id> --json        # fetched results carry content_url
-zenrows crawl content <id> <content_id>  # one page's HTML (or pass the content_url)
-zenrows crawl download <id> --out pages.jsonl  # every URL + HTML, NDJSON
+zenrows crawl content <id> <content_id>  # one page (or pass the content_url)
+zenrows crawl download <id> --out pages.jsonl  # every URL + page, NDJSON
 ```
 
-`--output-format html` uses up the page budget: each kept page is one more
+`--output-format html` stores each page as fetched; `--output-format markdown`
+stores it converted to Markdown. Either uses up the page budget: each kept page is one more
 fetch, and `--max-pages` counts it. Raise `--max-pages` to keep the same number
 of URLs. A result's `content_status` is `pending`, `fetched` or `failed`; only
 `fetched` results have content (else `CRAWL_CONTENT_NOT_FOUND`). `download`
@@ -75,8 +77,15 @@ zenrows crawl stop <id>                      # stop it; kept URLs stay readable
 ```
 
 A crawl ends `completed` (nothing left, or a cap hit: `stop_reason`
-`max_items` / `max_pages`), `stopped` (you stopped it) or `failed` (`error.code`
-and `error.detail` say why). Only `failed` exits non-zero (`CRAWL_FAILED`).
+`max_items` / `max_pages`), `stopped` or `failed` (`error.code` and
+`error.detail` say why). `stopped` with `stop_reason` `user` means you stopped
+it. `stopped` with no `stop_reason` and `error.code` `insufficient_credits` or
+`api_key_cap_reached` means the account ran out of credits or the API key hit a
+credit cap; the pages fetched before that stay readable. `failed`, and a
+`stopped` crawl with an `error`, exit non-zero: `CRAWL_INSUFFICIENT_CREDITS` or
+`CRAWL_KEY_CAP_REACHED` when credits ended it (the same codes a refused
+`create` gets, also when an older deployment reports it `failed`), else
+`CRAWL_FAILED`. `server_code` carries the API's `error.code`.
 `stop` on a crawl that already ended prints the status it ended with.
 
 With `--json`, `create`, `get`, `wait` and `stop` print
@@ -110,15 +119,15 @@ The "Retry?" column is for errors that remain after these retries.
 | --- | --- | --- |
 | `CRAWL_NOT_ENABLED` | 403 `REQS008`: Crawl is not enabled for this account | no |
 | `AUTH_INVALID` | 401: the API key was rejected | no, log in again |
-| `CRAWL_INSUFFICIENT_CREDITS` | 402: the account is out of credits (claim the account or add credits) | after credits renew or are added |
-| `CRAWL_KEY_CAP_REACHED` | 402 `AUTH014` or `api_key_cap_reached`: this API key reached its credit cap | after the cap resets or is raised |
+| `CRAWL_INSUFFICIENT_CREDITS` | 402 on `create`, or a crawl that ended on `insufficient_credits`: the account is out of credits (claim the account or add credits) | after credits renew or are added |
+| `CRAWL_KEY_CAP_REACHED` | 402 `AUTH014` or `api_key_cap_reached` on `create`, or a crawl that ended on `api_key_cap_reached`: this API key reached its credit cap | after the cap resets or is raised |
 | `CRAWL_INVALID_REQUEST` | 400 or 422: fix the request. For `idempotency_key_reused`, send a new key or no key | no, not as is |
 | `CRAWL_REQUEST_IN_FLIGHT` | 409: the same Idempotency-Key is still in flight | yes, once the first request ends |
 | `CRAWL_NOT_FOUND` / `CRAWL_CONTENT_NOT_FOUND` | 404: wrong id, or the page has no content | no |
 | `CRAWL_TOO_MANY_CRAWLS` | 429 `too_many_crawls` on `create`: the account's active-job limit | yes, after `retry_after` |
 | `CRAWL_RATE_LIMITED` | any other 429: requests are being throttled | yes, after `retry_after` |
 | `CRAWL_BUSY` | 503 `crawl_busy` on `stop`: the stop was not saved yet and the crawl still runs | yes, run the stop again after `retry_after` |
-| `CRAWL_FAILED` | the crawl ended `failed`, or another error | 5xx: yes, with backoff |
+| `CRAWL_FAILED` | the crawl ended `failed`, or `stopped` with an error other than credits, or another error | 5xx: yes, with backoff |
 | `BACKEND_UNAVAILABLE` | the API could not be reached | yes |
 
 Rules: start small (`--depth 1`, low caps) and check the results before a

package/skills/trace-debug/SKILL.md

@@ -49,12 +49,16 @@ zenrows trace export <run-id>     # JSON for sharing
   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`; `error.code` in
+- `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`.