Best practices

Retries and errors

Today most error responses collapse to 400 (your request is wrong — do not retry) or 500 (something failed on our side — retry with backoff). More granular codes are rolling out, so build your client to dispatch on the status code rather than parsing error bodies, and the guidance below will continue to apply as the surface area expands.

• Retry 5xx responses with exponential backoff (e.g. 1s, 2s, 4s, 8s) and jitter — a small random offset on each attempt — capped at a reasonable number of attempts (3–5). Jitter matters because it prevents clustered clients from all retrying in lockstep. Surface the failure once retries are exhausted rather than looping indefinitely.
• Do not retry 4xx responses. They mean your request itself is wrong — retrying with the same payload will keep failing and just add noise.
• When 429 Too Many Requests starts appearing (not common today, but coming as we roll out per-endpoint rate limits), retry with the same exponential-backoff-with-jitter strategy as 5xx. If the response carries a Retry-After header, use it as a minimum wait — keep growing your backoff from there if subsequent attempts also fail.
• Be careful retrying writes (POST/PUT/DELETE). If a request times out, the server may still have applied the change; retry only when you can detect or tolerate the duplicate.