Handle API errors and retries
Diagnose ShareAI authentication, scope, model-access and availability errors without duplicate writes or unsafe refresh retries.
On this page
Always inspect the HTTP status before reading a response as success. ShareAI services can return different error envelopes: inference may provide error.code, OAuth provides error and error_description, and Console routes can return code, message and data.status.
| Status | Typical meaning | Recovery |
|---|---|---|
| 200 with an error object | No-device availability result in the current chat endpoint. | Inspect error.code and do not render it as an assistant answer. |
| 400 | Invalid request or OAuth grant. | Correct the body, parameters, callback or expired/consumed code. |
| 401 | Missing, expired or invalid authentication. | Check the credential; refresh only a valid OAuth grant. |
| 402 | Insufficient credits or applicable balance. | Check the selected account balance before retrying. |
| 403 | Scope, ownership, role or enabled-state denial. | Check the documented permission boundary. |
| 404 | Unknown resource or unsupported gateway route. | Check the host, path and resource identifiers. |
| 409 | State or revision conflict. | Read current state and reconsider the change. |
| 429 | Request or concurrency limit. | Respect Retry-After and use a bounded backoff. |
| 500 / 502 / 503 | Server or upstream availability failure. | Keep retries bounded; preserve diagnostic identifiers. |
Retry reads with a limit#
For temporary failures on reads, wait with increasing delay and jitter, honor Retry-After when present and stop after a defined attempt or time budget. Show the user when data is unavailable instead of silently looping.
Treat writes carefully#
Do not automatically repeat a pricing update, model creation or sharing command when the outcome is unknown. Read the resource or command state first. Use an Idempotency-Key only on endpoints that document support, such as agreement changes.
Refresh tokens are single-use#
Refresh rotation needs a per-authorization lock in your backend. A blind retry of a consumed refresh token can revoke the grant. See safe token refresh.
What to include in a support request#
Include the endpoint, HTTP status, error code, time and response/task identifier when available. Remove Authorization headers, cookies, client secrets, access tokens, refresh tokens and private prompt contents.
Last updated September 15, 2026