Troubleshooting
Troubleshooting, retries, and security
First locate the failing boundary: Dashboard login, Key management, billing, or model gateway. Preserve request_id, time, and status, but never include a full Key.
Confirm Dashboard login, Key, balance, and models, then send a minimal cURL request. If it succeeds, inspect client configuration; otherwise continue with HTTP status and Usage.
- First
- Confirm current config
- Smoke test
- cURL
- Correlation
- request_id
- Never submit
- Full API Key
Recommended diagnostic order
- 1Confirm Dashboard signs in.
- 2Confirm the API Key works and review balance and account state in Dashboard.
- 3Recopy the Gateway, Key, and model ID.
- 4Call GET /v1/models to verify authentication.
- 5Send a minimal non-streaming cURL request.
- 6Move the same values back into the SDK, CLI, or IDE.
Model request error matrix
| Symptom | Check first |
|---|---|
| 400 | JSON, field types, required fields, and model parameters |
| 401 | Complete and active Key plus auth Header |
| 402 / 403 | Balance, account, or group access |
| 404 | Gateway, /v1 path, model catalog, and protocol |
| 429 | Retry-After, concurrency, burst rate, and upstream capacity |
| 5xx / timeout | Gateway reachability, temporary upstream failure, and client timeout |
Sign-in failures
- Use an authentication method currently offered on the login page.
- Complete any verification or security check shown by the page.
- Sign in again after a session expires.
- Follow the page guidance when registration requires sign-in or another method.
- Contact operations when the account is restricted.
Account and billing issues
| Symptom | Action |
|---|---|
| Balance not updated | Refresh Dashboard and review current purchase records |
| Purchase unavailable | Follow current Dashboard configuration and account permissions |
| Model request denied | Check balance, Key, model, and group access |
| Records differ | Keep timestamps and page records, then contact operations |
API Key issues
- Cannot create: check page validation, account state, and permissions.
- 401: recopy the complete Key and confirm the auth Header.
- New Key not active in a client: update its Secret and restart cached credentials.
- Before deletion, confirm no client still uses the Key.
- For persistent failures, keep time, error code, and request_id.
Streaming connections and retries
- Proxy and client read timeouts must cover first-token and long-response latency.
- Use SSE-compatible proxy settings and disable unnecessary buffering.
- Propagate AbortSignal or close the connection when the client cancels.
- Retry only 429, clearly temporary 5xx, or network failures with bounded exponential backoff.
- Do not restart a request after content has begun unless duplicates and extra cost are acceptable.
Diagnostic information to provide
| Safe to provide | Never provide |
|---|---|
| UTC time, request_id, related record ID, HTTP status | Full API Key or account password |
| Gateway host and path without credential query data | Authorization or x-api-key Header |
| Model ID, client/version, minimal reproduction | Sensitive prompt, full response, or personal data |
| Redacted error type/code | Internal management credentials |