# 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](mailto: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.