feat(client): retry uncharged failures by default, with full-jitter backoff and a time budget

[gonzalo-zenrows]

What changed

fetch(), extract() and post() now share one retry policy, the same one the Python SDK, Go SDK and CLI are adopting in parallel PRs:

• Retried: 429, 502, 503 and 504 (the API never charges these), and network errors before any response.
• Never retried: a timeout or abort (the server may still finish the request and charge it), and every other status. 422 is no longer retried: the API no longer sends a retryable 422. no_data_extracted was already final; now every 422 is.
• Wait between tries: the server's Retry-After in whole seconds, capped at 30 s. Otherwise full jitter: uniform(0.25 s, min(retryMaxWait, 1 s * 2^attempt)), where attempt is the 0-based retry index (first retry 0.25–1 s, second 0.25–2 s). An HTTP-date Retry-After falls back to jitter.
• Budget: no retry starts if the time spent since the first try plus the next wait would pass retryBudget. The last response or error is returned as-is.
• The extract() fallback to autoparse on REQS007 / AUTH010 is unchanged: still one extra request (which gets its own retries, as before).

It stays on fetch-retry, with no second retry layer: the policy lives in src/retry.ts and is passed per request as retryOn / retryDelay, so each request has its own clock and budget. A retried response's body is cancelled so its connection is freed.

New defaults

Option	Before	Now
retries	0	2
retryMaxWait (seconds)	—	30
retryBudget (seconds)	—	90

The retries default is a public behaviour change, so this is a feat (minor release with a changelog entry via release-please). Callers who already set retries get the new wait curve and status set.

How to opt out

const client = new ZenRows(apiKey, { retries: 0 });

Tests

pnpm check is clean. pnpm test -- --run: 403 passed, 6 skipped (e2e). Retry tests use fake timers and an injectable clock and random source, so they run in milliseconds:

• tests/retries.test.ts: retried and non-retried statuses, network error vs abort/timeout, jitter bounds per attempt, retryMaxWait cap, Retry-After honoured and capped at 30 s, non-numeric Retry-After falls back to jitter, budget respected (unit and end to end), no retry on 400/422, autoparse fallback unchanged.
• tests/retry-count.test.ts: default makes 3 calls on a 503; retries: 0 makes 1.
• tests/no-data-extracted.test.ts: a non-no_data_extracted 422 is now not retried.
• tests/index.test.ts: two exact-argument assertions on the wrapped fetch now use objectContaining, since each call also carries retryOn / retryDelay.

README updated to describe the policy and the new options.

Not covered

• The Batch and Crawl clients keep their own retry logic; this PR does not change them.
• Not exercised against the live API.

[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 #58
• CLI: feat(fetch): retry uncharged busy answers so a brief capacity wait does not fail the command cli#64
• MCP: feat(fetch): retry not-served scrape and extract calls so a busy API does not fail the tool call zenrows-mcp#80