Errors
Error Codes
When a request fails, check the HTTP status code first, then the error body. Work through the checklist at the bottom.
Last updated: 2026-08-03
401 API Key Error
| Symptom | 401 Unauthorized — tool reports invalid API Key |
| Cause | Truncated key, deleted key, missing Bearer prefix, wrong config field |
| Fix | Re-copy the key, verify Authorization: Bearer your-apihub-key, recreate if needed |
| Billed? | Usually no |
| Contact support? | Only if still failing after recreating the key |
403 Balance, Account, or Access Restricted
| Symptom | 403 with a message about balance, account, IP, model, or group access |
| Cause | Insufficient balance or subscription quota; disabled account; IP outside the Key allowlist; model not allowed by the Key; group access denied |
| Fix | Follow the response message: check balance and quota, account status, Key IP/model restrictions, and group access instead of only retrying or topping up |
| Billed? | Usually no when request did not complete |
| Contact support? | If balance looks incorrect |
413 Payload Too Large
| Symptom | 413 Payload Too Large |
| Cause | Input, files, context, or message history is too large |
| Fix | Shorten context, remove unnecessary files, reduce input size |
| Billed? | Usually no |
| Contact support? | Generally not needed |
429 Rate Limit / Too Many Requests
| Symptom | 429 Too Many Requests — CLI drops connection or fails repeatedly |
| Cause | Too many concurrent requests, tool auto-parallelism, rapid retries |
| Fix | Reduce concurrency, close extra sessions, wait and retry |
| Billed? | Usually no for incomplete requests |
| Contact support? | If it persists over a long period |
5xx Upstream / Server Error
| Symptom | 500, 502, 503, or 504 |
| Cause | Upstream model instability, network issue, temporary outage |
| Fix | Retry after a short wait, or switch to a different model |
| Billed? | Based on actual generation recorded in usage logs |
| Contact support? | If it continuously impacts usage |
Verification
- API Key is complete and not leaked.
- Base URL matches the protocol (OpenAI: with /v1, Anthropic: without).
- Model ID exists in the model list.
- Balance and quota are sufficient.
- No duplicate tool sessions running simultaneously.