Basic usage
Retries are off by default (retries: 0): the client sends each request once. Pass a retries count to the client constructor to turn them on:
retries: 2, a failed request is tried up to 3 times in all. The client then resolves with the last response it got.
This retry policy needs Node.js SDK 2.7.0 or later. If you upgrade with
retries already set, see Upgrading from earlier versions.When to enable retries
Enableretries (2-3 is a reasonable starting point) whenever you’re running requests at scale or in production, anywhere a transient failure shouldn’t fail your whole job. Leave retries: 0 (the default) for quick one-off scripts or debugging, where you’d rather see the raw failure immediately than wait through automatic retry attempts.
Which failures get retried
Withretries set, the client retries fetch(), get() and extract() after:
- A
429,502,503or504. - A
422, except Extract’s422with codeno_data_extracted, which is a final answer. - A failure to connect: a refused connection, a name that did not resolve, an unreachable network or host, or a connect timeout. The request never reached the API.
post(), whatever its headers. AnIdempotency-Keyheader is forwarded to the target site and does not change this.- Any other network error, such as a response timeout or a connection that closed after the request was sent. The API may still finish that request and charge it.
- A
500or any other status. The Python and Go SDKs do retry a500. - A status from the target site: any status when
original_statusis set, and a status listed inallowed_status_codes.
post(), write your own retry, and only when the target site can safely receive the same request twice. client.batch and client.crawl keep their own retry rules.
How long the SDK waits
- When the API sends
Retry-Afterin whole seconds, the client waits that long, from 0.25 to 30 seconds.retryMaxWaitdoes not change this. Any otherRetry-After, such as an HTTP date, is ignored. - Otherwise it waits a random time from 0.25 seconds up to 1 second before the first retry, 2 seconds before the second, 4 before the third, and so on, capped at
retryMaxWait. - A retry starts only if its wait ends within
retryBudgetseconds of the first try. A running try is not cut short, so a call can take longer than that.
AbortSignal, so a wait cannot be cancelled. While a call waits, it keeps its slot in the client’s queue (concurrency, default 5), so other calls on the same client can wait too.
retryMaxWait and retryBudget must be finite numbers above 0, or the constructor throws a RangeError. retries never throws: a numeric string such as "2" counts as its number, and a fraction rounds up. NaN, Infinity or a value that is not numeric turns retries off and logs one console.warn.
Upgrading from earlier versions
From Node.js SDK 2.7.0, an existingretries setting behaves differently. Calls with retries: 0 are unchanged. If you already set retries, check these changes:
- A
429and a502are now retried. post()is never retried.- A network error after the request was sent, a response timeout and an abort are no longer retried. A connect timeout still is.
- A status from the target site (
original_status,allowed_status_codes) is no longer retried. - Waits follow
Retry-Afteror a random backoff, instead of a fixed 1, 2, 4 seconds. No retry starts afterretryBudget(default 90 seconds). NaN,Infinityor a value that is not a number now turns retries off with one warning. Before, such a value retried without limit.
Handling failures
The SDK treats HTTP error status codes and network-level problems differently. Pick the tab that matches what you’re dealing with:- HTTP error status
- Network-level exceptions
Even after all retry attempts are exhausted, the SDK resolves with the final Unlike some HTTP libraries, native
Response object. It does not throw for a non-2xx status, matching how native fetch behaves. Always check the response before trusting its content:fetch (and this SDK) has no built-in raise_for_status() equivalent. Throw manually if you want an exception:Troubleshooting
- Response still fails after retries are exhausted: Check
response.statusand look it up in API Error Codes. Some failures (like an invalidapikey) won’t be fixed by retrying and need a code change instead. - A
500isn’t being retried: This is expected. The Node.js SDK returns a500at once. Retry it in your own code if it is transient. 429errors keep coming back after retries: You’re likely exceeding your plan’s concurrency limit, not hitting a one-off rate limit. Lower yourconcurrency, see Concurrency.- A
post()isn’t being retried: This is expected. The SDK sends everypost()once, with or without anIdempotency-Keyheader. Write your own retry if the target can safely receive the request twice. - Retries seem to take a long time: That’s the backoff by design. Lower
retriesorretryBudgetif latency matters more than success rate for your use case. - Getting a rejected promise instead of an error response: That only happens for network-level failures (DNS errors, dropped connections), not HTTP error status codes. Wrap the call in
try/catchas shown above.
Pricing
Retried attempts that fail are not billed. Only the final successful response counts. This makesretries effectively free insurance against transient failures:
404 and 410 responses count as successful and are billed, since the request itself completed correctly.FAQ (Frequently Asked Questions)
What's the default number of retries?
What's the default number of retries?
- Retries are off unless you pass
retriesto the constructor.
Why doesn't the SDK retry 500 responses?
Why doesn't the SDK retry 500 responses?
The Node.js SDK returns a
500 at once, even with retries set. The Python and Go SDKs retry it. Retry a 500 in your own code if you need to.Am I charged for retried requests that eventually fail?
Am I charged for retried requests that eventually fail?
No. Only successful requests consume your Zenrows balance.
Look up a specific error code
For a full breakdown of Zenrows error codes (likeAUTH002 or RESP001) and how to resolve each one, see the API Error Codes reference.