Integration guides ยท 2026-09-22
Handling timeout and connection errors in Muse Spark Contributor
Covers error classes other than 429, meaning timeouts and connection drops, and explains why they need a different retry logic than a 429 does.
429 and timeout are not the same family
As the 429 retry article for Muse Spark Contributor explains, quota exhaustion is clearly marked by an HTTP status code, and the wait time can usually be read from a response header. A timeout or a connection drop is a different error family: the request may have reached the server, may not have, or the response may have been lost in transit; that ambiguity calls for a different approach than the clarity a 429 provides.
Missing this distinction and retrying every error with the same fixed wait can make you wait unnecessarily long on a timeout, or give up too early on a connection issue.
On a timeout, the request's fate is uncertain
When a request times out, you cannot tell whether the server never received it, received it but failed to produce a response, or produced a response that failed to reach you. Retrying a request with no side effect (pure text generation) directly is usually safe. But if the request has a side effect (submitting a data contribution, for example), blindly resending the same request carries a risk of the operation happening twice.
A connection drop (a connection reset, a DNS error) usually points to a network-layer issue, and the request is more likely to have never reached the server at all; retrying directly on this kind of error carries lower risk than on a quota error.
- Timeout: the request's fate is uncertain; don't blindly resend requests with side effects.
- Connection drop: usually indicates the request never reached the server; retrying carries lower risk.
- Unlike the clear wait time on a 429, use exponential backoff on a timeout.
Don't retry without an upper limit
Timeouts and connection errors need an upper retry limit just like a 429 does; otherwise a persistent network problem can turn into an infinite retry loop. Reporting the error clearly once the limit is reached, instead of silently swallowing it, lets the problem get noticed.
Frequently asked questions
Should I use the same fixed wait time on a timeout as on a 429?
No. On a 429, the wait time can usually be read clearly from a response header; there is no such information on a timeout, so proceeding with increasing wait times (exponential backoff) is more appropriate.
Is it safe to retry a request with a side effect after a timeout?
Not certain; whether the request was actually processed on the server is ambiguous. For requests with side effects, checking whether the operation happened with a separate query before resending, where possible, is safer.