Skip to main content
Web scraping requests occasionally fail for transient reasons, like a temporary server hiccup or a connection that fails to open. The SDK can retry these automatically so you don’t have to write that logic yourself.

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:
With 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

Enable retries (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.
Don’t also wrap the client in your own retry loop: the tries multiply. With retries: 2 (3 tries) inside a loop of 4 tries, one call can send up to 12 requests.

Which failures get retried

With retries set, the client retries fetch(), get() and extract() after:
  1. A 429, 502, 503 or 504.
  2. A 422, except Extract’s 422 with code no_data_extracted, which is a final answer.
  3. 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.
It never retries:
  1. post(), whatever its headers. An Idempotency-Key header is forwarded to the target site and does not change this.
  2. 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.
  3. A 500 or any other status. The Python and Go SDKs do retry a 500.
  4. A status from the target site: any status when original_status is set, and a status listed in allowed_status_codes.
To retry a 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

  1. When the API sends Retry-After in whole seconds, the client waits that long, from 0.25 to 30 seconds. retryMaxWait does not change this. Any other Retry-After, such as an HTTP date, is ignored.
  2. 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.
  3. A retry starts only if its wait ends within retryBudget seconds of the first try. A running try is not cut short, so a call can take longer than that.
The client takes no 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.
You aren’t charged for retried attempts that fail. Only successful responses count toward your usage. See the Retry Failed Requests guide for more on how this works.

Upgrading from earlier versions

From Node.js SDK 2.7.0, an existing retries setting behaves differently. Calls with retries: 0 are unchanged. If you already set retries, check these changes:
  • A 429 and a 502 are 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-After or a random backoff, instead of a fixed 1, 2, 4 seconds. No retry starts after retryBudget (default 90 seconds).
  • NaN, Infinity or 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:
Even after all retry attempts are exhausted, the SDK resolves with the final Response object. It does not throw for a non-2xx status, matching how native fetch behaves. Always check the response before trusting its content:
Unlike some HTTP libraries, native 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.status and look it up in API Error Codes. Some failures (like an invalid apikey) won’t be fixed by retrying and need a code change instead.
  • A 500 isn’t being retried: This is expected. The Node.js SDK returns a 500 at once. Retry it in your own code if it is transient.
  • 429 errors keep coming back after retries: You’re likely exceeding your plan’s concurrency limit, not hitting a one-off rate limit. Lower your concurrency, see Concurrency.
  • A post() isn’t being retried: This is expected. The SDK sends every post() once, with or without an Idempotency-Key header. 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 retries or retryBudget if 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/catch as shown above.

Pricing

Retried attempts that fail are not billed. Only the final successful response counts. This makes retries 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)

  1. Retries are off unless you pass retries to the constructor.
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.
No. Only successful requests consume your Zenrows balance.

Look up a specific error code

For a full breakdown of Zenrows error codes (like AUTH002 or RESP001) and how to resolve each one, see the API Error Codes reference.