Skip to main content
The Go SDK separates two kinds of failure: errors returned before a request is even sent (bad configuration, invalid parameters, malformed URLs), and unsuccessful HTTP responses that still come back as a valid *Response. Retries, once you turn them on, apply to the second kind, and to a connection that failed before the request was sent.

Basic usage

Retries are off by default (maxRetryCount is 0): the client sends each request once. Pass WithMaxRetryCount to turn them on:
With WithMaxRetryCount(3), a failed request is tried up to 4 times in all. The client then returns the last response or error it got.
This retry policy needs Go SDK service/api v1.4.0 or later. If you upgrade with a retry count already set, see Upgrading from earlier versions.

When to enable retries

Enable retries (2 to 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 off (the default) for quick one-off scripts or debugging, where you’d rather see the raw failure immediately.
Don’t also wrap the client in your own retry loop: the tries multiply. With WithMaxRetryCount(2) (3 tries) inside a loop of 4 tries, one call can send up to 12 requests.

Which failures get retried

With WithMaxRetryCount set, the client retries a GET (Get, Fetch, Extract, or Scrape with GET) after:
  1. A 429, 500, 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 a connect timeout. The request never reached the API.
It never retries:
  1. A POST or PUT, whatever its headers, or a GET whose body is an io.Reader. An Idempotency-Key header in RequestParameters.CustomHeaders is forwarded to the target site and does not change this.
  2. Any other network error, such as a read timeout or a connection reset after the request was sent. The API may still finish that request and charge it.
  3. A canceled or expired context.
  4. Any other status.
  5. A status from the target site: any status when ReturnOriginalStatus is set, and a status listed in AllowedStatusCodes.
To retry a POST or PUT, write your own retry loop, and only when the target site can safely receive the same request twice.

How long the SDK waits

  1. When the API sends Retry-After in whole seconds, the client waits that long, from 250ms to 30 seconds, even above WithRetryMaxWaitTime. Any other Retry-After, such as a date, is ignored.
  2. Otherwise it waits a random time between 250ms and RetryWaitTime * 2^n, where n is 0 for the first retry, capped at WithRetryMaxWaitTime. With the defaults, that is up to 1 second before the first retry, 2 seconds before the second, and so on.
  3. A retry starts only if its wait ends within the retry budget (WithRetryBudget) of the first attempt. A running attempt is not cut short, so a call can take longer than that.
To stop a call, cancel its context: the wait ends at once and the client sends no further request. While a call waits, it keeps its WithMaxConcurrentRequests slot, so other calls on the same client can wait too.
WithMaxRetryCount(-1) makes every call return an InvalidOptionError and send no request. With a retry count above 0, so does a negative WithRetryWaitTime, or a WithRetryMaxWaitTime or WithRetryBudget of 0 or less. With no retry count, the other retry options are not checked.
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 service/api v1.4.0, an existing retry count behaves differently. A client with no retry count is unchanged. If you already set WithMaxRetryCount, check these changes:
  • A 502, 503 and 504 are now retried.
  • A POST or PUT is never retried, on any status or error.
  • Only a failed connection is retried. A reset or EOF after the request was sent, a read timeout, a TLS error and a proxy error are not.
  • A GET whose body is an io.Reader is no longer retried.
  • A status from the target site (ReturnOriginalStatus, AllowedStatusCodes) is no longer retried.
  • WithRetryWaitTime is now the base of a random backoff, default 1s. It was a minimum wait, default 5s. Every wait is at least 250ms.
  • A Retry-After from the API sets the wait, up to 30 seconds, even above WithRetryMaxWaitTime. No retry starts after 90 seconds.
  • An invalid retry option makes every call return an InvalidOptionError, and WithMaxRetryCount(-1) no longer panics.

Handling failures

Even after retries are exhausted, the SDK returns a *Response with err == nil. It doesn’t turn a non-2xx status into a Go error on its own. Always check the response before trusting its content:

The SDK error types

All are returned as values (not pointers), and InvalidTargetURLError supports errors.Unwrap so you can inspect the underlying parse error with errors.As or errors.Is.

Troubleshooting

  • Response still fails after retries are exhausted: Check response.StatusCode() and look it up in API Error Codes. Some failures, like an invalid API key, aren’t fixed by retrying.
  • Getting InvalidParameterError for a parameter you didn’t set: Several RequestParameters fields depend on each other, for example, ScreenshotFullPage requires Screenshot: true, and WaitForSelector requires JSRender: true. Check Validate()’s rules in the SDK source if the message isn’t specific enough.
  • 429 errors even with retries: You’re likely exceeding your plan’s concurrency limit, not hitting a one-off rate limit. See Concurrency.
  • Retries seem to take a long time: That’s the backoff by design. A Retry-After from the API can make a wait up to 30 seconds. Lower WithMaxRetryCount or WithRetryBudget if latency matters more than success rate.

Pricing

Retried attempts that fail are not billed. Only the final successful response counts:
404 and 410 responses count as successful and are billed, since the request itself completed correctly.

FAQ

Zero. Retries are off unless you pass WithMaxRetryCount(n) with n > 0.
422 (except no_data_extracted), 429, 500, 502, 503 and 504, plus a connection that failed before the request was sent. A POST or PUT is sent once and never retried.
No. A non-2xx HTTP response is still a successful round trip from the SDK’s point of view, it returns a *Response with err == nil. Check response.IsError() or response.StatusCode() yourself.

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.