> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zenrows.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> The Zenrows HTTP API serves Fetch and Extract (extract=auto) at https://api.zenrows.com/v1/, Crawl at https://api.zenrows.com/v1/crawls, and Batch at https://async.api.zenrows.com/v1. Fetch, Extract, Crawl and Batch are described in OpenAPI 3.1 at https://www.zenrows.com/openapi.json and listed in the RFC 9727 API catalog at https://www.zenrows.com/.well-known/api-catalog. Every endpoint also has its own page under /api-reference with its schema. Use the spec for exact parameter names and types. Crawl's endpoints, parameters and errors are also at https://docs.zenrows.com/crawl/endpoints.md. To call Zenrows from an agent, connect the MCP server at https://mcp.zenrows.com/mcp. To search these docs from an agent, connect the docs MCP server at https://docs.zenrows.com/mcp. Agent skills for Zenrows are published at https://github.com/ZenRows/cli and install with `npx skills add ZenRows/cli`.

# Retry failed requests

> Retry Zenrows requests that hit temporary errors, with growing waits between tries, and fix the ones that need a change to the request.

At scale, some Fetch requests meet a transient condition: a page that loads slowly on one attempt, a busy moment, a connection that fails to open. Retry those with growing waits and they go through. Requests that don't succeed aren't charged, so a retry costs the attempt that succeeds.

**Uses:** [Fetch](https://docs.zenrows.com/fetch/api-reference.md) with [Adaptive Stealth Mode](https://docs.zenrows.com/fetch/features/adaptive-stealth-mode.md) (`mode=auto`), the [API error codes](https://docs.zenrows.com/api-error-codes.md) and the SDKs' [Python retries](https://docs.zenrows.com/fetch/sdk/python/error-handling-and-retries.md), [Node.js retries](https://docs.zenrows.com/fetch/sdk/nodejs/error-handling-and-retries.md) and [Go retries](https://docs.zenrows.com/fetch/sdk/go/error-handling-and-retries.md)

## Ask your AI agent

With the [Zenrows MCP server](https://docs.zenrows.com/mcp/overview.md) connected to Claude, Cursor or any MCP client, paste this prompt. Your agent picks the right Zenrows tools and settings on its own.

```text theme={"theme":"css-variables"}
Use Zenrows to read each of these URLs. If a request fails with a temporary error,
wait a few seconds and retry it, up to 3 times. If it fails because of the request itself,
don't retry: tell me the error code and what to fix.
https://www.scrapingcourse.com/ecommerce/
https://www.scrapingcourse.com/ecommerce/product/abominable-hoodie/
```

The MCP server's `scrape` and `extract` tools send each call once by default. On the local server, set `ZENROWS_FETCH_RETRIES` to make them retry a `429`, `502`, `503` or `504`, and a connection that failed before the request was sent, before your agent sees the error. See [Retries in `scrape` and `extract`](https://docs.zenrows.com/mcp/tool-reference#retries-in-scrape-and-extract).

> [!WARNING]
>
> Retries stack. With `ZENROWS_FETCH_RETRIES=2`, each `scrape` or `extract` call can send up to 3 requests, so "retry up to 3 times" (4 calls) can send up to 12 requests for one URL. The same holds for your own retry loop around an SDK client with retries turned on.

## Which errors to retry

Retry the errors that can succeed on the next attempt. Fix the ones that return the same answer every time.

| Status | Example codes | What to do |
| - | - | - |
| `422` | [RESP001](https://docs.zenrows.com/api-error-codes.md#RESP001) | Retry. On a fixed configuration, switch to `mode=auto` so Zenrows escalates |
| `429` | [AUTH006](https://docs.zenrows.com/api-error-codes.md#AUTH006), [AUTH008](https://docs.zenrows.com/api-error-codes.md#AUTH008) | Retry with backoff, and lower your concurrency to `Concurrency-Limit` |
| `500`, `502`, `503`, `504` | [RESP009](https://docs.zenrows.com/api-error-codes.md#RESP009), [CTX0002](https://docs.zenrows.com/api-error-codes.md#CTX0002) | Retry with backoff and jitter |
| Connection refused, DNS failure or connect timeout | | Retry. The request never reached Zenrows |
| Read timeout, or a connection closed after the request was sent | | Don't retry blindly. Check your dashboard first, and keep the client timeout at 180 seconds or more |
| `400` | [REQS002](https://docs.zenrows.com/api-error-codes.md#REQS002), [REQS004](https://docs.zenrows.com/api-error-codes.md#REQS004) | Fix the parameters. For `REQS002`, use `mode=auto` |
| `401` | [AUTH001](https://docs.zenrows.com/api-error-codes.md#AUTH001), [AUTH002](https://docs.zenrows.com/api-error-codes.md#AUTH002) | Fix the API key |
| `402` | [AUTH004](https://docs.zenrows.com/api-error-codes.md#AUTH004), [AUTH014](https://docs.zenrows.com/api-error-codes.md#AUTH014) | Top up or raise the credit cap |
| `403`, `404` | [AUTH009](https://docs.zenrows.com/api-error-codes.md#AUTH009), [RESP002](https://docs.zenrows.com/api-error-codes.md#RESP002) | Fix the account or the target URL |

Every error body is JSON with a `code` field: log it with the URL so you can group failures by cause.

A read timeout on your side does not stop the request at Zenrows. Zenrows may still finish and charge it, and the request keeps its concurrency slot until it ends. A blind retry can pay twice and run into `429`. If your dashboard shows no matching request, it never reached Zenrows, and you can send it again. See [Cancelled request behavior](https://docs.zenrows.com/fetch/api-reference.md#cancelled-request-behavior).

## Retry with backoff in your own code

This function retries the retryable statuses with waits of 1, 2 and 4 seconds plus random jitter, switches a fixed configuration to `mode=auto` after a `422`, and stops at once on errors that need a fix. It retries a connection that never reached Zenrows, and raises a read timeout or a dropped connection instead of retrying it.

```python Python (Requests) theme={"theme":"css-variables"}
import random
import time

import requests
from urllib3.exceptions import NewConnectionError

API_KEY = "YOUR_ZENROWS_API_KEY"
RETRY_STATUSES = {422, 429, 500, 502, 503, 504}

def never_reached_zenrows(error):
    # Connect timeout, connection refused or DNS failure: safe to send again.
    reason = getattr(error.args[0], "reason", None) if error.args else None
    return isinstance(error, requests.ConnectTimeout) or isinstance(reason, NewConnectionError)

def fetch_with_retries(url, params=None, max_attempts=4):
    params = {"apikey": API_KEY, "url": url, **(params or {})}

    for attempt in range(1, max_attempts + 1):
        # A read timeout (requests.ReadTimeout) is not caught here, so it raises at once.
        try:
            response = requests.get("https://api.zenrows.com/v1/", params=params, timeout=180)
        except requests.ConnectionError as error:
            if not never_reached_zenrows(error):
                # Closed after the request was sent: Zenrows may still be working on it.
                raise
            print(f"Attempt {attempt}: network error ({type(error).__name__})")
        else:
            if response.ok:
                return response
            if response.status_code not in RETRY_STATUSES:
                # 400, 401, 402, 403, 404: retrying returns the same answer. Fix the request.
                raise RuntimeError(f"{response.status_code}: {response.text}")
            try:
                code = response.json().get("code")
            except ValueError:  # a body that isn't JSON, such as a proxy error page
                code = None
            print(f"Attempt {attempt}: {response.status_code} {code}")

            # A 422 on a fixed configuration: let Adaptive Stealth Mode pick one instead.
            if response.status_code == 422 and "mode" not in params:
                params.pop("js_render", None)
                params.pop("premium_proxy", None)
                params["mode"] = "auto"

        if attempt < max_attempts:
            delay = min(2 ** (attempt - 1), 30) + random.uniform(0, 1)  # 1s, 2s, 4s ... plus jitter
            time.sleep(delay)

    raise RuntimeError(f"Gave up on {url} after {max_attempts} attempts")

response = fetch_with_retries("https://www.scrapingcourse.com/ecommerce/")
print(response.status_code, len(response.text), "bytes")
```

```javascript Node.js theme={"theme":"css-variables"}
const API_KEY = "YOUR_ZENROWS_API_KEY";
const RETRY_STATUSES = new Set([422, 429, 500, 502, 503, 504]);
// Connection refused, DNS failure or connect timeout: the request never reached Zenrows.
const NOT_SENT_CODES = new Set([
  "ECONNREFUSED", "ENOTFOUND", "EAI_AGAIN", "ENETUNREACH", "EHOSTUNREACH", "UND_ERR_CONNECT_TIMEOUT",
]);
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function fetchWithRetries(url, extraParams = {}, maxAttempts = 4) {
  const params = { apikey: API_KEY, url, ...extraParams };

  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    try {
      const response = await fetch(`https://api.zenrows.com/v1/?${new URLSearchParams(params)}`, {
        signal: AbortSignal.timeout(180_000),
      });
      if (response.ok) return response;

      const body = await response.text();
      if (!RETRY_STATUSES.has(response.status)) {
        // 400, 401, 402, 403, 404: retrying returns the same answer. Fix the request.
        throw Object.assign(new Error(`${response.status}: ${body}`), { final: true });
      }
      let code;
      try {
        code = JSON.parse(body).code;
      } catch {
        code = undefined; // a body that isn't JSON, such as a proxy error page
      }
      console.log(`Attempt ${attempt}: ${response.status} ${code}`);

      // A 422 on a fixed configuration: let Adaptive Stealth Mode pick one instead.
      if (response.status === 422 && !params.mode) {
        delete params.js_render;
        delete params.premium_proxy;
        params.mode = "auto";
      }
    } catch (error) {
      if (error.final) throw error;
      // A timeout or a connection closed after sending: Zenrows may still be working on it.
      if (!NOT_SENT_CODES.has(error.cause?.code)) throw error;
      console.log(`Attempt ${attempt}: network error (${error.cause.code})`);
    }

    if (attempt < maxAttempts) {
      const delay = Math.min(2 ** (attempt - 1), 30) * 1000 + Math.random() * 1000; // 1s, 2s, 4s ... plus jitter
      await sleep(delay);
    }
  }
  throw new Error(`Gave up on ${url} after ${maxAttempts} attempts`);
}

const response = await fetchWithRetries("https://www.scrapingcourse.com/ecommerce/");
console.log(response.status, (await response.text()).length, "bytes");
```

## Example output

A page that loads on the first attempt returns at once:

```text theme={"theme":"css-variables"}
200 82776 bytes
```

A target that keeps failing, here `https://httpbin.io/status/503`, comes back from Zenrows as `422` with code `RESP001` on every attempt. The function retries it with growing waits, then reports it:

```text theme={"theme":"css-variables"}
Attempt 1: 422 RESP001
Attempt 2: 422 RESP001
Attempt 3: 422 RESP001
Attempt 4: 422 RESP001
Gave up on https://httpbin.io/status/503 after 4 attempts
```

None of those attempts is charged.

## Retry with a Requests session

If you already use a `requests.Session`, mount urllib3's `Retry` on it and every call through the session retries on its own. `backoff_jitter` needs urllib3 2.x, which current `requests` installs.

```python Python (Requests) theme={"theme":"css-variables"}
import requests
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry

retries = Retry(
    total=3,                     # up to 3 retries after the first attempt
    read=False,                  # never retry a read timeout or a connection closed after sending
    other=0,                     # nor any other error after the request was sent
    backoff_factor=1,            # waits 0s, 2s, 4s between attempts
    backoff_jitter=1,            # plus up to 1s of random jitter
    status_forcelist=[422, 429, 500, 502, 503, 504],
    respect_retry_after_header=True,
    raise_on_status=False,       # hand back the last response instead of raising
)

session = requests.Session()
session.mount("https://", HTTPAdapter(max_retries=retries))

params = {"apikey": "YOUR_ZENROWS_API_KEY", "url": "https://www.scrapingcourse.com/ecommerce/"}
response = session.get("https://api.zenrows.com/v1/", params=params, timeout=180)
print(response.status_code)
```

This retries with the same parameters each time. Use the function above when you also want the switch to `mode=auto` on `422`.

## Use the SDKs' built-in retries

The SDK clients send each request once by default. Pass a retry count to turn retries on: `retries` in Python and Node.js, `WithMaxRetryCount` in Go. The client then retries for you, with a random wait that grows with each retry. Install with `pip install zenrows`, `npm install zenrows` or `go get github.com/zenrows/zenrows-go-sdk/service/api`.

```python Python (SDK) theme={"theme":"css-variables"}
from zenrows import ZenRowsClient

client = ZenRowsClient("YOUR_ZENROWS_API_KEY", retries=3)

response = client.fetch("https://www.scrapingcourse.com/ecommerce/", params={"mode": "auto"}, timeout=180)
print(response.status_code, response.headers["X-Request-Credits"], "credit")
```

```javascript Node.js (SDK) theme={"theme":"css-variables"}
import { ZenRows } from "zenrows";

const client = new ZenRows("YOUR_ZENROWS_API_KEY", { retries: 3 });

const response = await client.fetch("https://www.scrapingcourse.com/ecommerce/", { mode: "auto" });
console.log(response.status, response.headers.get("X-Request-Credits"), "credit");
```

Output: `200 1 credit`. When every attempt fails, the client returns the last response, so check its status as usual.

| SDK | Retries on |
| - | - |
| Python `ZenRowsClient(retries=N)` | `422`, `429`, `500`, `502`, `503`, `504`, and a connection that failed before the request was sent |
| Node.js `new ZenRows(key, { retries: N })` | `422`, `429`, `502`, `503`, `504`, and a connection that failed before the request was sent |
| Go `scraperapi.WithMaxRetryCount(N)` | `422`, `429`, `500`, `502`, `503`, `504`, and a connection that failed before the request was sent |

All three return Extract's `422` with code `no_data_extracted` at once, because it is a final answer. None retries a POST or PUT, any other network error such as a read timeout, or a status from the target site (`original_status`, `allowed_status_codes`). They wait the API's `Retry-After` in whole seconds, from 0.25 to 30 seconds, and a retry starts only if its wait ends within 90 seconds of the first try. See [Python retries](https://docs.zenrows.com/fetch/sdk/python/error-handling-and-retries.md), [Node.js retries](https://docs.zenrows.com/fetch/sdk/nodejs/error-handling-and-retries.md) and [Go retries](https://docs.zenrows.com/fetch/sdk/go/error-handling-and-retries.md) for every option. Combine `retries` with `concurrency` to run many requests safely, see [Run many requests concurrently](https://docs.zenrows.com/academy/fetch/concurrent-requests.md).

## Customize it

| Change | How |
| - | - |
| More or fewer attempts | Change `max_attempts`, `total` or `retries` |
| Longer waits for busy targets | Raise the base delay or the 30-second cap |
| Retry a whole list that failed | Collect failed URLs and run them again, or let [Batch](https://docs.zenrows.com/academy/scrape-from-a-list-of-urls.md) rerun failed tasks |
| Fewer `429` errors | Size your pool to `Concurrency-Limit`, see [Run many requests concurrently](https://docs.zenrows.com/academy/fetch/concurrent-requests.md) |
| Look up any error code | See [API error codes](https://docs.zenrows.com/api-error-codes.md) |

## Troubleshooting

* **Every retry returns the same `422`**: the configuration is too light for that site. Switch to `mode=auto`, or add `js_render=true` and `premium_proxy=true`. When content loads late, add `wait_for`.
* **`429` keeps coming back during retries**: retries add to the requests in flight. Lower your pool size and keep the backoff.
* **A `400` comes back without a retry**: the request itself needs a fix. Read the `code` and see [API error codes](https://docs.zenrows.com/api-error-codes.md).
* **`499` or timeouts on your side**: your client gave up before Zenrows finished. Set the timeout to 180 seconds or more before adding retries.

## Related recipes

> [card] [Resolve common response codes](https://docs.zenrows.com/academy/production/fix-common-errors.md)
>
> The fix for each error code you are likely to see.

> [card] [Run many requests concurrently](https://docs.zenrows.com/academy/fetch/concurrent-requests.md)
>
> Size your pool to your plan and keep 429s away.

> [card] [Scrape pages protected by anti-bot systems](https://docs.zenrows.com/academy/fetch/protected-sites.md)
>
> Let Adaptive Stealth Mode pick the right configuration per page.

> [card] [Scrape a list of URLs](https://docs.zenrows.com/academy/scrape-from-a-list-of-urls.md)
>
> Let Batch queue, retry and store results for you.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.