*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:
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 transient429 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.
Which failures get retried
WithWithMaxRetryCount set, the client retries a GET (Get, Fetch, Extract, or Scrape with 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, an unreachable network, or a connect timeout. The request never reached the API.
- A
POSTorPUT, whatever its headers, or aGETwhose body is anio.Reader. AnIdempotency-Keyheader inRequestParameters.CustomHeadersis forwarded to the target site and does not change this. - 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.
- A canceled or expired context.
- Any other status.
- A status from the target site: any status when
ReturnOriginalStatusis set, and a status listed inAllowedStatusCodes.
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
- When the API sends
Retry-Afterin whole seconds, the client waits that long, from 250ms to 30 seconds, even aboveWithRetryMaxWaitTime. Any otherRetry-After, such as a date, is ignored. - Otherwise it waits a random time between 250ms and
RetryWaitTime * 2^n, wherenis 0 for the first retry, capped atWithRetryMaxWaitTime. With the defaults, that is up to 1 second before the first retry, 2 seconds before the second, and so on. - 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.
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.
Upgrading from earlier versions
Fromservice/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,503and504are now retried. - A
POSTorPUTis 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
GETwhose body is anio.Readeris no longer retried. - A status from the target site (
ReturnOriginalStatus,AllowedStatusCodes) is no longer retried. WithRetryWaitTimeis now the base of a random backoff, default1s. It was a minimum wait, default5s. Every wait is at least 250ms.- A
Retry-Afterfrom the API sets the wait, up to 30 seconds, even aboveWithRetryMaxWaitTime. No retry starts after 90 seconds. - An invalid retry option makes every call return an
InvalidOptionError, andWithMaxRetryCount(-1)no longer panics.
Handling failures
- HTTP error status
- SDK and network errors
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
InvalidParameterErrorfor a parameter you didn’t set: SeveralRequestParametersfields depend on each other, for example,ScreenshotFullPagerequiresScreenshot: true, andWaitForSelectorrequiresJSRender: true. CheckValidate()’s rules in the SDK source if the message isn’t specific enough. 429errors 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-Afterfrom the API can make a wait up to 30 seconds. LowerWithMaxRetryCountorWithRetryBudgetif 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
What's the default number of retries?
What's the default number of retries?
Zero. Retries are off unless you pass
WithMaxRetryCount(n) with n > 0.Which status codes trigger an automatic retry?
Which status codes trigger an automatic retry?
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.Does the SDK ever return a Go error for a non-2xx response?
Does the SDK ever return a Go error for a non-2xx response?
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 (likeAUTH002 or RESP001) and how to resolve each one, see the API Error Codes reference.