Errors
The OpenAI-compatible error envelope and the full Zumik error-code table, with HTTP status, meaning, and how to fix each one.
Zumik returns errors in the exact OpenAI envelope on /v1, and the same shape on /v2 for consistency. Existing OpenAI SDK error handling works unchanged. Error bodies never leak internal details.
The error envelope
Every error response is a single error object:
{
"error": {
"message": "Missing or invalid API key.",
"type": "invalid_request_error",
"code": "invalid_api_key",
"param": "messages"
}
}error.messagestringA human-readable description of what went wrong. Safe to surface to a developer; never contains secrets or internal stack detail.
error.typestringThe error class. One of invalid_request_error, rate_limit_error, insufficient_quota, api_error, or idempotency_conflict.
error.codestring | nullA stable machine-readable code for branching in client logic. Present on most errors; omitted for generic validation and not-found cases.
error.paramstring | nullThe request field that caused a validation error, when one applies (for example messages or input_file_id). Omitted otherwise.
Branch on type and code, not on message text, which may be refined over time.
Error-code table
| HTTP | type | code | Meaning | How to fix |
|---|---|---|---|---|
| 400 | invalid_request_error | (none) | The request body or a parameter is malformed or missing. param names the offending field. | Correct the field named in param and retry. |
| 401 | invalid_request_error | invalid_api_key | The bearer token is missing, malformed, or unknown. | Send a valid Authorization: Bearer zk_live_... header. See authentication. |
| 401 | invalid_request_error | invalid_credentials | Console login credentials were wrong (login plane only). | Re-authenticate in the console. Not used by the bearer-key API. |
| 402 | invalid_request_error | credits_required | The project's prepaid credit balance is empty, so inference is refused. | Add credits in the console, then retry. |
| 403 | invalid_request_error | insufficient_scope | The key authenticated but lacks the scope for this action (for example managing aliases with an inference-only key). | Use a key with the required scope (for example admin). |
| 403 | invalid_request_error | region_not_allowed | The request would route to a region the project's regional policy forbids. | Adjust the regional policy, or send traffic that resolves to an allowed region. See QoS and policy. |
| 404 | invalid_request_error | (none) | The addressed object (response, conversation, batch, file, model) does not exist for this project. | Check the id and that it belongs to the authenticated project. |
| 409 | invalid_request_error | branch_version_conflict | An optimistic-concurrency append lost the race: the branch moved since you read its version. | Re-read the branch head and replay the append with the current expected_version. |
| 409 | idempotency_conflict | (none) | A request with the same Agent-Idempotency-Key is still in progress. | Wait for the original to settle, then retry. See idempotency. |
| 429 | insufficient_quota | quota_exceeded | A project or per-key spending budget is reached. | Raise the cap or enable overage in the console. |
| 429 | rate_limit_error | rate_limit_exceeded | The per-key request-rate limit was exceeded (throughput, not budget). | Back off and retry with exponential backoff. See rate limits. |
| 502 | api_error | (none) | An upstream provider failed and no fallback path succeeded. | Retry; if it persists, the resolved provider is degraded. |
| 504 | invalid_request_error | deadline_exceeded | The request's QoS deadline_ms elapsed before the provider responded, so Zumik aborted it. The request is not charged. | Raise deadline_ms in your agent hints, or accept the slower result. |
Handling retries
429 and 504 are transient and safe to retry with backoff. The rate_limit_error type signals a throughput problem (slow down), while insufficient_quota signals a money problem (raise the cap or enable overage). To make a retry safe against double-charging, attach an idempotency key. See idempotency and retries for the full pattern.
A 504 deadline timeout never charges the request, because Zumik bails before the provider result is recorded.
Authentication
Bearer API keys (zk_live_...), per-key spending budgets, and the 401 error shape Zumik returns for a missing or invalid key.
Idempotency
Use Agent-Idempotency-Key to make retried POST requests safe, the agent-idempotent-replay response header, and the replay and in-flight-conflict semantics.