Record the HTTP status, redacted error body, model ID and timestamp, then identify whether the client, gateway or provider failed. A status code is a starting point, not enough on its own to decide to retry or add credit.
Capture useful, redacted diagnostics
Record the method, path, timestamp, model and returned request ID if present. Keep the error type and message but remove Authorization, cookies, keys and sensitive input. Avoid screenshots of terminals containing credentials.
If the response is HTML instead of expected JSON, check the domain, path and proxy error pages. Reduce the request to a verified model and minimal text to isolate new parameters or inputs.
401 / 403: check credentials and permissions
401 commonly indicates missing or invalid authentication. Check Bearer formatting, empty environment variables and revoked keys. 403 often indicates a policy or permission rejection, which may also come from a proxy; inspect the body.
Retries do not repair a bad key. If exposed, revoke it in the dashboard and update server configuration. Avoid broadening access to every model just to hide a specific configuration problem.
429: distinguish rate limits from quota
Check for Retry-After, rate-limit details or quota messages. For temporary rate limits, reduce concurrency and retry according to provider guidance or bounded backoff with jitter. Quota and permission issues need an account or configuration change first.
5xx / timeouts: check whether work already ran
Gateway failures, provider errors and network timeouts can all look like a failed request. Check request records before retrying. For asynchronous media jobs, query the original task; for agents with external actions, verify whether those actions completed.
Set a retry limit and overall deadline rather than retrying forever. When contacting the operator, provide redacted diagnostics and a minimal reproduction, never the full key.
References
Our approach: state prerequisites, cite primary sources and distinguish platform capabilities from enabled services. Guides make no performance or AI recommendation guarantees.
