[gonzalo-zenrows]

Why

zenrows fetch and zenrows extract sent each request once. A brief busy answer (429, 502, 503 or 504) failed the command, although Zenrows does not charge these answers. A 503 RESP009 told agents to rerun with --manual --js-render --premium-proxy. That is the most expensive configuration, and it does not help.

This PR applies the retry policy that every Zenrows Fetch and Extract client shares.

What changes

1. Retried statuses. The CLI retries 429, 502, 503 and 504 up to --retries <n> times. The flag is new on fetch and extract. The default is 2, and 0 sends the request once.
2. Retried network errors. The CLI retries a network error only when the request never reached the API. That means a refused connection, a name that did not resolve, a connect timeout or an unreachable network.
3. Connect timeouts. A host with several addresses gets one connect per address family. The CLI retries only when every connect failed, so the request was never sent. A connect timeout (ETIMEDOUT on connect) counts as such a failure, but a read timeout never does.
4. Not retried. The CLI never retries its own timeout, or a connection that closed after the request was sent. In both cases the API may still finish the request and charge it.
5. Target statuses. Under --original-status, or when allowed_status_codes lists the status, the 429 or 5xx may be the target site's page. The CLI sends it once.
6. Delay. Retry-After counts when it is whole digits. The CLI waits that many seconds, at least 0.25 s and at most 30 s. Otherwise it waits uniform(0.25 s, min(30 s, 1 s × 2^attempt)), where attempt counts retries from 0.
7. Budget. No retry starts after 90 s, counted from the command's first request. The budget does not stop a running request, so a command can take longer than 90 s.
8. Timeout. The default --timeout rises from 120 s to 200 s. The API's own budget is 180 s, and the public docs tell clients to wait at least that long. A test again guards that the default stays above the budget.
9. SERVICE_BUSY. A 503 RESP009 now returns this new error. It says the request was not charged. It quotes the API's own title, which tells the two Extract meanings apart. The next action says to wait and run the same command again.
10. The same command. SERVICE_BUSY and the final error after a retried 429, 502, 503 or 504 suggest the command that ran. The suggestion keeps the extract method and every flag, quoted for a shell. These errors no longer advise --js-render or --premium-proxy.
11. Attempts. With --json, the result has a new attempts field. It counts the HTTP requests the command sent, so 1 means no retry.
12. extract prepare is not retried. Its endpoints answer 429 when the monthly allowance is used up and 503 when preparation is unavailable. Those are answers, not busy signals. The command keeps its own client and sends each request once, and a test guards that.
13. Shared helper. src/core/backoff.ts holds the delay schedules. Crawl keeps its own schedule and its own reading of Retry-After, so its behaviour does not change.
14. Docs. The fetch and extract help, the README Fetch section, and the protected-fetch, trace-debug and extract skills describe all of the above.

Behaviour change

Agents that branched on FETCH_FAILED for a 503 RESP009 now see SERVICE_BUSY. A command that hits a busy API now takes longer before it fails, but no retry starts after 90 s. A slow request now waits up to 200 s before the CLI gives up, instead of 120 s. A connection that closes after the request was sent now fails at once instead of being retried. The --json result gains an attempts field, and no existing field changes. Exit codes stay the same. zenrows extract prepare behaves as it does on main.

Not covered

A 429 page that is not JSON and mentions "upgrade" or "credit" is now retried. After the retries, the existing quota check still reports it as POLICY_MAX_CREDITS_EXCEEDED. That check also serves zenrows usage, so changing it belongs in a separate PR. Under --original-status, a RESP009 from Zenrows itself is now sent once, because the CLI cannot always tell it from a target page. Error envelopes other than --json results do not report the attempt count. The CLI has no cancel option of its own; Ctrl-C ends the command, including a wait between retries. I did not run any of this against the live API.

Testing

1. npm ci, npm run typecheck and npm test pass on the branch head: 588 tests, 0 failures, on Node 26 locally. That count includes every test from main, among them the extract prepare tests. CI runs Node 20 and 22.
2. tests/fetch-retry.test.ts holds the shared conformance tables for Retry-After, jitter bounds and the retry decision. It also checks the 90 s budget on both paths and exact waits with a fixed random source.
3. Three tests use real node:http sockets. A refused port gets three attempts, on 127.0.0.1 and on localhost. A server that closes the connection after reading the request gets one.
4. tests/fetch-retry-command.test.ts runs the fetch and extract commands. It checks the suggested command for each extract method and a manual fetch. It also checks --retries 0, the attempts field, and that extract prepare sends a 429 or 503 once.
5. I ran the built CLI against a local mock API. A 503 RESP009 on fetch and on extract --css ... --json made three requests each and suggested the exact command. extract prepare and extract prepare status made one request per endpoint on a 429 or 503.
6. I reverted each change in turn on a copy of the tree. Every mutation made at least one test fail.

[gonzalo-zenrows]

Same retry policy across all clients (429/502/503/504 and pre-response connection errors; 2 retries by default; full jitter; Retry-After capped at 30 s; 90 s total budget; timeouts never retried):

• Python SDK: feat(client): retry only failures another try can fix, with jittered backoff zenrows-python-sdk#62
• Go SDK: feat(api): retry transient failures by default with full-jitter backoff zenrows-go-sdk#43
• Node SDK: feat(client): retry uncharged failures by default, with full-jitter backoff and a time budget zenrows-node-sdk#58
• CLI: feat(fetch): retry uncharged busy answers so a brief capacity wait does not fail the command #64
• MCP: feat(fetch): retry not-served scrape and extract calls so a busy API does not fail the tool call zenrows-mcp#80

[jonathan-zenrows]

Looks good, I'd merge after the rebase (it conflicts with main). Checked: typecheck clean, 505/505 tests pass, and the retry notices go to stderr, so piped --json stays clean.

Two things go beyond what the other 4 PRs do. We should decide whether all of them get them or this one drops them:

• a 429 with AUTH004/AUTH014 is not retried (src/core/http.ts:89, 219)
• with --original-status or an allowed_status_codes that covers the status, nothing is retried (http.ts:227-234). That includes a real 503 RESP009 from ZenRows. If you keep it, I'd still retry when the body is a ZenRows error with a retryable code.

Small:

• with happy-eyeballs, a connect timeout on one address family arrives as an AggregateError with code: ETIMEDOUT. It isn't in NEVER_SENT_CODES, so it isn't retried. It's a connect, so it's safe to retry: check syscall === 'connect'.
• clearTimeout runs before res.arrayBuffer() (http.ts:309-314), so reading the body has no timeout, and a failure mid-body throws a raw TypeError instead of a ToolkitError. This was already in main, but the docblock at l.270 now says the opposite.
• the comment in src/adapters/protected-fetch.ts:48-51 should give the numbers (200 s vs 180 s) like http.ts does.
• README §8 Extract doesn't mention --retries.