Retries, timeouts and AI API errors: avoid making one problem two
Know when to retry, when to fix the request and how to avoid duplicating asynchronous work.

Read the failure before repeating it
A malformed request, invalid key or unsupported parameter usually needs a configuration change, not another identical attempt. Rate limits and temporary service errors may be worth retrying according to the endpoint documentation. Capture the status and request identifier, while keeping credentials and sensitive prompts out of logs.
Authentication and permission errors call for a key and access review. Invalid request format, model name or parameter calls for a request change. A rate limit or temporary service failure may be retryable. Follow the endpoint’s documented status and error format; calling every case a “network error” hides useful information and can trigger pointless repeats.
Give temporary failures room to recover
For retryable failures, use a bounded retry policy with backoff and jitter, and respect a server-provided retry delay when available. Set an overall deadline so a user is not left waiting indefinitely. Do not retry every error, and avoid synchronizing many clients into a single burst.
For errors the documentation permits retrying, cap both attempts and total time, increase the delay and add jitter to avoid many clients retrying together. Respect an explicit server-provided delay. Let the user cancel, and stop when the budget is exhausted instead of consuming resources indefinitely in the background.
A retry waits and follows a controlled path around a temporary failure.Be careful with work that has side effects
A timeout can happen after a request was accepted. Creating a second image or video task may duplicate work and charges. Persist the original task identifier when one is returned, check its status before resubmitting, and use idempotency support only when the endpoint explicitly documents it.
A timeout after task submission can mean the response was lost even though the remote task was created. Save and check an ID when received; without one, do not assume the task does not exist. Check whether the endpoint documents lookup, callbacks or idempotency and follow its recovery process. Explain the possibility of additional charges before creating another task.
Design the message for the person waiting
Tell users whether they can retry, change an input or come back later. Keep partial streamed text visible when appropriate and make clear that it is incomplete. Test an invalid request, a rate limit, a network interruption and a delayed task separately; they should not all lead to the same generic message.
Time, request ID, endpoint, status, duration and a necessary error category are often enough to begin an investigation. Do not log complete keys, authorization headers or unnecessary user prompts; review personal data before sharing a log. Users need a clear next step, while maintainers need traceable but limited diagnostic context.
Simulate invalid parameters, authentication failure, rate limiting, connection interruption and a slow asynchronous task separately. Check that only suitable errors are retried, delays are bounded and the interface preserves partial results where appropriate. Test repeated clicks on retry for duplicate tasks. An exercise should not need real customer data or submit billable jobs to production.
Identify the type of failure
Keep the status code, request ID, time and a redacted error category. Authentication failures call for checking credentials or permissions; invalid fields require changing the request; rate limits and temporary service failures may be retryable. Follow the endpoint's response and documentation rather than sending every failure into the same loop.
A timeout after submission does not prove the remote service did nothing. The request may still be processing or may have completed while its response was lost. For task creation and other side effects, that distinction matters. Tell users whether their input is preserved and what they can do next without exposing keys or internal stack traces.
Set limits on retries
For failures that are safe to retry, set a maximum attempt count and a total waiting budget. Increasing the delay and adding random jitter can reduce simultaneous retries across many clients. Follow any applicable wait guidance from the response or documentation; an example delay is not a universal service limit.
Avoid multiplying retries across browser, backend and client library: decide which layer owns the policy and record outcomes. Before retrying a write or creation, use an idempotency mechanism the service actually supports or check the known task state. If neither is reliable, report the uncertainty rather than assuming duplicate execution is harmless.
Test the policy with two examples
If a text request receives an explicit rate-limit response, keep the user's input, retry only within the allowed wait and attempt limits, and allow cancellation. If recovery fails, say so instead of showing an endless spinner.
If a video submission loses its connection before the task ID arrives, the result is uncertain. Use the endpoint's supported recovery mechanism if one exists; don't silently create multiple jobs. Test invalid keys, bad parameters, dropped connections and cancellations as well. Tune alerts by duration and impact so a brief recovered failure does not hide a serious incident.
Two failures that need different responses
If a request is rate-limited and the service provides a retry delay, wait as directed within your retry budget. If a video creation request times out after submission, the task may already exist: look for its saved identifier and check its status first. If no identifier was received, report the uncertainty and follow the endpoint’s documented recovery method instead of assuming that resubmission is free.
When contacting support, provide the time, model name and request ID with a sanitized description of the error. Never ask a user to post a key or complete private content in a public channel. Check whether a task was already created before recommending a safe next step or retry.