Errors
Merius returns OpenAI-style error responses. Reference for every HTTP status and error type, what causes it, and how to handle it.
Every error uses the same OpenAI-compatible JSON envelope, so existing error handling in the OpenAI
SDKs works unchanged. The HTTP status code tells you how to react; the type field groups errors
by cause.
The error shape
{
"error": {
"message": "a human-readable description",
"type": "invalid_request_error",
"code": "invalid_request"
}
}message is safe to log or surface. type is stable and safe to branch on. A 429 also carries a
Retry-After header.
Status codes
Merius never exposes which upstream served (or failed) a request. Error messages are generic by design — they describe what went wrong, never where.
| Status | type | Meaning | What to do |
|---|---|---|---|
400 | invalid_request_error | Malformed request — bad JSON, missing model, or a parameter the model rejects. | Fix the request. Not retryable as-is. |
401 | authentication_error | Missing or invalid API key. | Check the Authorization: Bearer <key> header and that the key is active. |
402 | insufficient_quota | Your prepaid balance is exhausted. | Top up your account in the dashboard, then retry. |
403 | permission_error | The key is valid but not permitted to use the requested model (a model-scoped key). | Use a model the key allows, or a key without model restrictions. |
404 | invalid_request_error | The requested model is not on this API. | Call /v1/models to see available model slugs. |
413 | invalid_request_error | Request body too large. | Reduce the prompt size or max_tokens. |
429 | rate_limit_error | Rate limited, or the service is momentarily at capacity. | Back off and retry — honor the Retry-After header. Retryable. |
Retrying safely
- Retry
429responses (and only those) with exponential backoff, honoringRetry-After. The official OpenAI SDKs do this for you. - Do not retry
400,401,402,403,404, or413unchanged — the request itself needs to change first.
A 429 does not mean your request was wrong — it means "retry shortly." Merius returns 429
(rather than a 5xx) when no capacity is momentarily available, so a transient hiccup is always
cleanly retryable.