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 returns the last response it got.
This retry policy needs Python SDK 1.13.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 429 or 5xx 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 a GET after:
- A
429,500,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, or a connect timeout. The request never reached the API.
- A POST or PUT, whatever its headers, or a request with
filesor a stream body. AnIdempotency-Keyheader is forwarded to the target site and does not change this. - Any other network error, such as a read timeout or a connection that closed after the request was sent. The API may still finish that request and charge it.
- Any other status, such as
400,401,402,403or404. - A status from the target site: any status when
original_statusis set, and a status listed inallowed_status_codes.
How long the SDK waits
- When the API sends
Retry-Afterin whole seconds, the client waits that long, from 0.25 to 30 seconds.retry_max_waitdoes 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
retry_max_wait. - A retry starts only if its wait ends within
retry_budgetseconds of the first try. A running try is not cut short, so a call can take longer than that.
fetch_async and the other async methods. While an async call waits, it keeps its worker in the client’s thread pool (concurrency, default 5), so other async calls on the same client can wait too.
retry_max_wait and retry_budget must be finite numbers above 0, or the constructor raises ValueError. Pass retries as an int: a bool or a float still works with a DeprecationWarning (True is 1, 2.5 is 2), and None or a string raises TypeError. You can also set client.retries after you create the client; the next call uses it.
Upgrading from earlier versions
From Python SDK 1.13.0, an existingretries setting behaves differently. Calls with retries=0 are unchanged. If you already set retries, check these changes:
- A PUT is no longer retried on a
429or5xx, and a POST or PUT is no longer retried on a422or a failed connection. - A read timeout or a connection that closed after the request was sent is no longer retried. A read timeout now raises
requests.ReadTimeoutinstead ofrequests.ConnectionError, so catchrequests.ReadTimeouttoo. - A TLS error or any other error that is not a failed connection is no longer retried.
- 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 0, 1, 2, 4 seconds. No retry starts afterretry_budget(default 90 seconds).
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 returns the final If you’d rather fail loudly, call
requests.Response object. It does not raise an exception for a non-2xx status. Always check the response before trusting its content:response.raise_for_status(), which raises requests.exceptions.HTTPError for 4xx/5xx responses:Troubleshooting
- Response still fails after retries are exhausted: Check
response.status_codeand look it up in API Error Codes. Some failures (like an invalidapikey) won’t be fixed by retrying and need a code change instead. - Retries seem to take a long time: That’s the backoff by design. Lower
retriesorretry_budgetif latency matters more than success rate for your use case. - Getting exceptions instead of error responses: That only happens for network-level failures (timeouts, DNS errors), not HTTP error status codes. Wrap the call in
try/except requests.exceptions.RequestExceptionas shown above. - 429 errors even with retries: You’re likely exceeding your plan’s concurrency limit, not hitting a one-off rate limit. See Async Requests and Concurrency.
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
What's the default number of retries?
What's the default number of retries?
The default number of retries is 0. Retries are off unless you pass
retries=N to the constructor.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.
Does the SDK retry on connection timeouts automatically?
Does the SDK retry on connection timeouts automatically?
Yes for a connect timeout, once you set
retries: that request never reached the API. A read timeout is not retried. It raises requests.ReadTimeout at once, because the API may still finish and charge that request. Handle both with your own try/except, as shown above.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.