> For the complete documentation index, see [llms.txt](https://docs.kontinent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kontinent.ai/best-practices/retries-and-backoff.md). # Retries & backoff Kontinent handles provider-level failover for you, but your client still needs a sane retry strategy for the errors that reach it. ## Decide by status code

:rotate:

Retriable429, 500, 502 upstream_error. Use exponential backoff with jitter.

:ban:

Not retriable as-is400, 401, 403, 404. Fix the request or the key first.
* `401 invalid_api_key`: the key is wrong or revoked. Retrying with the same key will not help. * `402 insufficient_credits`: retriable only after a top-up lands. * `403 segment_not_permitted`: choose a model from another provider instead of retrying. * `429 rate_limit_exceeded`: your key's RPM window is full. Back off for at least the 60 s window. * `429 upstream_rate_limited`: the provider throttled us, not you. Retry with backoff. See the full [error taxonomy](/features/errors.md) for every code. ## Streaming needs a different rule Failover between providers only happens **before the first byte** of a stream. Once tokens start arriving, an upstream failure looks like a dropped connection, not a clean HTTP error. Treat a stream that ends without `data: [DONE]` as a retriable failure on your side, and remember that the tokens generated up to that point are already billed. See [Streaming](/features/streaming.md). ## A reasonable default For most clients, exponential backoff with jitter, starting around 200 ms to 500 ms and capping at a few seconds, handles both `429` cases and transient `5xx` errors well. Stop retrying after a small, fixed number of attempts and surface the failure; do not retry indefinitely. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.kontinent.ai/best-practices/retries-and-backoff.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.