Errors and troubleshooting
Gateway errors use an OpenAI-style error object with a message, type, code, and request ID where available. Inspect the code and message as well as the HTTP status.
| Situation | What to do |
|---|---|
| Invalid request or unsupported parameter | Correct the payload using the selected model's request contract |
| Authentication failure | Check the Bearer header and whether the key was deleted, suspended, or expired |
| Permission or model-access failure | Check account status, enabled models, and current discovery |
| Insufficient credits or a spending ceiling | Check the wallet and request limits before retrying |
| Unavailable model or not-found response | Refresh discovery; do not silently change the selected model |
409 idempotency conflict | Use the original request semantics with the original key, or a new key for a new operation |
429, 502, 503, or 504 | Retry only eligible transient errors with a bounded policy; honor Retry-After |
Retry deliberately
Use exponential backoff with jitter and a finite retry count. Send a stable Idempotency-Key for a logical operation that may be retried, preserving the request semantics. Authentication, policy, credit, and validation failures need correction rather than repeated requests.
For supported long-running non-streaming calls, Prefer: respond-async can return 202 and a status URL. Poll that URL with the same API key, honoring Retry-After. See the agent guide for the complete contract.
Get help
Email Support@the-code.org with the request ID, timestamp, endpoint, status, and a description of the issue. Remove keys, tokens, prompts, and personal data from any examples. Do not send full authorization headers.