SDKs
Retries and timeouts
Every generated client retries failed requests with exponential backoff and jitter, and bounds each call with a timeout. You don't have to configure any of it: these settings are for when the defaults don't fit your API.
Set them project-wide in SDK Studio, or on a single endpoint when one method needs different treatment.
The settings
| Setting | What it does | Range |
|---|---|---|
| Max attempts | Total tries, including the first | 1 to 10 |
| Backoff | The first retry's delay, before jitter | Up to 2 minutes |
| Max backoff | Ceiling on any single delay | Up to 10 minutes |
| Retry status codes | Which HTTP statuses trigger a retry | Any 100 to 599 |
| Timeout | How long one attempt can take before it aborts | Up to 10 minutes |
Leave a field blank and the client keeps its built-in default, so you only override what you mean to.
1 disables retries. 3 means the original request plus two retries.
Precedence
- The client's built-in
What ships when you configure nothing.
- Your project default
Set in Studio. Applies to every method.
- A per-endpoint override
Applies to one method only.
Merging is per-field, so an endpoint that only sets Timeout keeps your project's Max attempts and Retry status codes.
Choosing what to retry
A POST that times out may still have succeeded on the server. Retrying it creates a second resource unless the server can recognise the repeat. That's what idempotency keys are for, and why generated clients send one on writes by default.
Before adding a write status to Retry status codes, make sure idempotency is on.
A sensible set covers failures that are plausibly transient:
| Status | Retry? | Why |
|---|---|---|
408 | Yes | Request timeout |
429 | Yes | Rate limited, and backing off is the correct response |
500, 502, 503, 504 | Yes | Server-side and often transient |
400, 422 | No | The request is wrong; retrying sends the same wrong request |
401, 403 | No | The credential is wrong; retrying won't fix it |
404 | No | Rarely helps, and hides a real bug |
Backoff
Delay grows exponentially from Backoff and is capped by Max backoff. Jitter is applied automatically, so a fleet of clients that fail together don't retry in lockstep and hammer a recovering service.
Max attempts of 8 with no Max backoff can leave a caller waiting minutes on a doomed request. The ceiling is what bounds the worst case.
Timeouts
Timeout bounds one attempt, not the whole retry sequence. Three attempts at ten seconds each can occupy roughly thirty seconds plus backoff against a dead server.
Set it to 0 to disable, and only where a long call is expected, such as a streamed endpoint.