HopBase DocsError codes and retries
HopBase error response shapes, what each status code means and whether it is retryable, how streaming failures surface, and what to include when you report a problem.
To look up a specific symptom, use Troubleshooting. This page is the full reference. For concurrency caps, timeouts and billing, see Concurrency, timeouts, and billing.
Error response shape
OpenAI protocol (/v1/chat/completions, /v1/responses, /v1/images/*, /v1/video/*):
{ "error": { "message": "…", "type": "invalid_request_error", "code": "insufficient_quota" } }Anthropic protocol (/v1/messages):
{ "type": "error", "error": { "type": "invalid_request_error", "message": "…" } }Message language follows the Accept-Language request header and defaults to English. In code, branch on the HTTP status and code, never on the message text.
Status codes
| Status | Typical cause | Retryable | What to do |
|---|---|---|---|
| 401 | Missing, truncated, disabled or expired key | No | Copy the key again from API Keys in the console, or create a new one |
| 402 | Account balance exhausted; key quota exhausted; video submission not covered by the balance reservation | After topping up | Top up or raise the key quota; do not retry in a loop |
| 403 | The plan restricts which clients may call it, or the capability is not enabled | No | Use a client or plan that supports the call |
| 404 | The model is not in this key's plan, the path does not belong to it, or the plan is retired | No | Call GET /v1/models with this key to confirm the ID; for paths see Base URL and protocols |
| 413 | Request body over 60 MB | No | Compress the media, or pass a URL where the model supports it |
| 429 | Account or key concurrency cap reached, or the model is rate limited right now | Yes | Retry after Retry-After and lower your concurrency |
| 499 | The client disconnected before completion (manual stop or read timeout) | Yes | Stream long outputs and raise the client read timeout |
| 502 / 503 | The model is temporarily unavailable; automatic failover already retried | Yes | Back off and retry, or switch to another model in the same family |
| 504 | The request timed out upstream | Yes | Back off and retry; use streaming or async endpoints for long jobs |
One 404 actually means «temporarily unavailable»
If you get Model "X" is not supported by any configured account in this group, call GET /v1/models with the same key first. If the model is listed, it is only temporarily unavailable — handle it like 502 / 503. Only if it is not listed does the plan really lack that model.
Retry rules
- Never retry unchanged: 400, 402, 403, 404, 413, 422. Fix the request, the configuration or the balance first.
- Retry with backoff: 429, 502, 503, 504, and interrupted streams. Suggested delays are 2s, 5s and 15s, up to three attempts.
- 429 carries retry hints:
Retry-After(seconds) andRetry-After-Ms(milliseconds). Honour them when present. - Never resubmit an accepted async job: a successful video or async image submission has already created a task. Resubmitting creates extra tasks that are each billed. Poll the task instead.
Streaming failures
Once a streaming response starts, the HTTP status is already 200 and never changes. Later failures arrive as events:
- OpenAI protocol:
event: error, orresponse.failedon the Responses protocol. - Anthropic protocol:
event: error.
Handle error events inside your read loop. Partial output cannot be resumed — reissue the whole request.
When reporting a problem
- The
x-request-idresponse header — every response carries one and it identifies that exact request - The time (with timezone) and the model ID
- The full error text and HTTP status
Contact us with those and we can trace the request directly.