Ottili AI API

Ottili AI API — Errors

HTTP status codes and machine-readable error codes returned by the public, OpenAI-compatible Ottili AI API.

The Ottili AI API uses standard HTTP status codes and returns a machine-readable

error body on failure. The envelope keeps OpenAI field names so existing

SDKs parse it unchanged; vendor extensions live under error.ottili.

The full error-semantics table (status → code mapping, retryability) is part of the public API contract documented in this reference. This page is the fastest reference.

Error body

{
  "error": {
    "message": "Model `ottili/helix-1.2` is not available.",
    "type": "invalid_request_error",
    "param": "model",
    "code": "model_not_found",
    "ottili": {
      "request_id": "req_...",
      "trace_id": "trc_...",
      "retryable": false,
      "retry_after": null
    }
  }
}

Field	Description
`message`	Human-readable summary. Never contains a raw provider message or secret.
`type`	OpenAI error type (`invalid_request_error`, `authentication_error`, `permission_error`, `rate_limit_error`, `api_error`).
`param`	The offending request field, when known.
`code`	Stable, machine-readable Ottili error code (table below).
`ottili`	Vendor extension: `request_id`, `trace_id`, `retryable`, `retry_after`.

Common codes

Code	HTTP	Meaning
`invalid_api_key`	401	Missing or invalid `Authorization` header, or expired token.
`insufficient_balance`	402	Managed-credit balance (or worst-case reservation) too low; top up or lower `max_tokens`.
`permission_error`	403	Missing `ai:chat` scope, abused/suspended key, or tenant denial.
`model_not_found`	404	Unknown, legacy (`helix`), or reserved (`spire`) model.
`idempotency_conflict`	409	Replay of an in-flight request with the same `Idempotency-Key`.
`prompt_too_large`	413	Estimated prompt exceeded the model's context safety bound.
`invalid_request_error`	422	Request body failed schema validation (e.g. bad `tools`, `temperature` out of range).
`rate_limit_exceeded`	429	Rate limit (RPM/TPM) exceeded; honour `Retry-After`.
`upstream_error`	502	Provider returned an error (raw message never leaked).
`upstream_timeout`	503	Provider timed out.
`capability_unsupported`	400	Model lacks the requested capability (e.g. reasoning on Vale, cached control on a non-cache provider).
`capability_constraint_violated`	400	Scalar parameter (temperature/top_p/penalty/n) outside its bounded range.
`tool_boundary_violation`	400	Tool schema/choice/iteration violated the allow-list or crossed a tenant boundary.

Troubleshooting

401 — verify the Authorization: Bearer otk_... header and that the key was not rotated.
403 scope — your key lacks ai:chat; request it from your admin. A suspended/abused key must be cleared by abuse review.
404 model — use ottili/vale-1.2, ottili/cairn-1.2, or ottili/auto. ottili/spire-1.2 is reserved (not served); legacy helix ids are rejected fail-closed.
409 — you replayed a request with the same Idempotency-Key while it was still in flight; reuse the key only for a true retry of the same logical request.
429 — honour Retry-After and add exponential backoff.
402 — top up credits or lower max_tokens; the reservation is worst-case, so a smaller cap may pass.

The same error conventions apply across the public developer surface, so one client

can handle AI and non-AI endpoints uniformly.

Was this article helpful?

Ottili AI API — Errors

Error body

Common codes

Troubleshooting

Related articles