Guides
Errors
Understand common HTTP errors, gateway errors, and retry behavior.
Error shape
Most errors return JSON with an `error` object:
{
"error": {
"message": "Invalid API key",
"type": "invalid_request_error",
"code": "unauthorized"
}
}Common errors
| HTTP | Meaning | Typical cause | Suggested action |
|---|---|---|---|
| 400 | Bad request | Invalid JSON, parameter range, unsupported field. | Validate request schema. |
| 401 | Unauthorized | Missing, revoked, or malformed API key. | Create or rotate a key in `/app/keys`. |
| 403 | Forbidden | Account, key, model, or workspace is not allowed. | Check model access and workspace policy. |
| 404 | Not found | Wrong endpoint path or model ID. | Confirm the base URL includes `/v1`. |
| 408 | Timeout | Upstream or network took too long. | Retry with backoff or reduce payload size. |
| 409 | Conflict | Duplicate operation or state conflict. | Refresh state and retry safely. |
| 422 | Validation failed | Required field missing or invalid. | Fix request body. |
| 429 | Rate limited | RPM, TPM, quota, or balance issue. | Back off and review `/app/usage`. |
| 500 | Internal error | Gateway or provider error. | Retry if safe; record request ID. |
| 502/503/504 | Upstream unavailable | Provider outage, route failure, timeout. | Retry with backoff or choose another model. |
Retry policy
Use exponential backoff with jitter for `408`, `429`, `500`, `502`, `503`, and `504`. Do not blindly retry non-idempotent tool calls or actions that may have side effects.
Balance and quota
If the account has no balance or quota, requests may fail with `429` or a billing-specific error. Check `/app/credits`, `/app/subscription`, and `/app/usage`.
Debug checklist
- Confirm the API key is active.
- Confirm the base URL is correct.
- Confirm the model ID exists on `/models`.
- Check `/status` for incidents.
- Open `/app/logs` and inspect status, route, latency, and error message.