Error codes
Two sources of errors: the OpusGate gateway itself (auth, connectivity — flat JSON bodies) and the upstream model provider (validation, balance, model errors — passed through verbatim in the Anthropic/OpenAI error format your SDK already understands).
Gateway errors
| Status | Body | Meaning | What to do |
|---|---|---|---|
401 | {"error": "missing_api_key"} | No key in the request. | Send the key as Authorization: Bearer or x-api-key. |
401 | {"error": "invalid_api_key"} | Key unknown, revoked, or has stray whitespace. | Re-paste the key; if in doubt, issue a fresh one on the Keys page. |
403 | {"error": "account_frozen"} | The account is suspended. | Contact support@opusgate.dev. |
429 | rate limit exceeded | More than 600 requests in a minute from your client. | Back off and retry; see rate limits. |
500 | {"error": "key_unavailable"} | Internal key-storage error on our side. | Not your fault — retry once, then contact support. |
502 | {"error": "upstream_unreachable"} | The upstream provider did not accept the connection. | Transient — retry with backoff. |
504 | {"error": "upstream_timeout"} | The request ran longer than the 180 s gateway timeout. | Use streaming for long generations, or reduce max_tokens. |
Upstream errors (passed through)
These arrive in the provider's native shape, e.g. {"type": "error", "error": {"type": "...", "message": "..."}} for the Anthropic protocol — so SDK error classes and retry logic keep working unmodified.
| Status | Type | Meaning | What to do |
|---|---|---|---|
400 | invalid_request_error | Malformed body — bad parameter, missing max_tokens, oversized context. | The error message names the field; fix the request. |
402 | insufficient balance | Your credit balance can’t cover the request. | Top up and retry — no reconfiguration needed. |
404 | not_found_error | Unknown model ID. | Copy the exact ID from the catalog — IDs are case-sensitive. |
429 | rate_limit_error | Upstream throughput limit for your tier. | Retry with exponential backoff. |
500 / 529 | api_error / overloaded_error | The model provider itself is erroring or overloaded. | Retry with backoff, or switch models temporarily. |
Rule of thumb
4xx → something about your request or account: fix key, balance, or body and retry. 5xx / 429 / 529 → transient: retry with exponential backoff. If a 5xx persists for more than a few minutes, write to support@opusgate.dev.