Errors, limits, and request IDs
Handle Codius API errors safely and make support reports actionable.
Treat 4xx responses as request, authentication, organization, entitlement, or quota problems. Retry only transient 429 and 5xx responses, with bounded exponential backoff and jitter.
Log the response status, stable error code, and Codius request ID. Do not log API keys, prompts, model output, or tool arguments.
Status guide
| Status | Meaning | Client action |
|---|---|---|
400 | Invalid shape, unsupported field, unsupported model capability, or another request error | Correct the request; do not retry unchanged |
401 | Missing or invalid API key | Replace or rotate the credential |
403 | Missing scope, organization access, entitlement, or policy permission | Correct access or choose an allowed operation |
404 | Unknown route or resource | Verify the base URL, path, and resource identifier |
409 | Current state conflicts with the requested mutation | Refresh state before deciding whether to retry |
429 | Concurrency, rate, or usage boundary | Respect reset metadata and retry with bounded backoff only when appropriate |
5xx | Transient service failure | Retry idempotent work with backoff and a maximum attempt count |
The structured error code is more specific than the HTTP status. For example, an unsupported model feature is rejected rather than silently removed from the request.
Request IDs
Every response includes:
x-codius-request-id: req_...Capture it from both success and error responses. A useful support report contains:
- request ID;
- UTC timestamp;
- HTTP method and path;
- status and stable error code;
- public model ID;
- client library and version;
- whether the response was streaming;
- a sanitized description of expected and observed behavior.
Never include the bearer token, full prompt, private source, model output, or tool arguments unless support explicitly requests a narrowly sanitized example.
Backoff
Use exponential backoff with jitter and a hard cap. Honor an explicit retry or reset header when the contract provides one. Stop retrying if the operation is non-idempotent, the credential is invalid, the request is unchanged after 400, or the user cancels.
For agent tools that can mutate external systems, distinguish retrying the model request from replaying the tool call. A duplicated tool call can be more damaging than a failed completion.
Usage-window responses
Inference responses expose percentage and reset-time headers for the five-hour, weekly, and monthly windows. When a usage boundary stops a request, show the relevant reset time and whether explicitly enabled wallet usage is available. Do not translate a normalized usage percentage into a guaranteed token count.
Last reviewed 2026-07-28 · Capability verified · Public docs are adapted and capability-checked before publication.
Provenance: apps/web/content/docs/api/errors.mdx from CodiusAI/codius at working-tree.