Errors

Failed requests return a single error object with a stable code and a matching HTTP status; the request id travels in the response headers.

Error object

On failure the response body is a single error object with message, a fixed type of advancedmind_error, and a stable code. The HTTP status matches the code. The request id is returned in the x-request-id response header and is the identifier support will ask for.

error.json

{
  "error": {
    "message": "available credits $0.000000 are below estimated request charge $0.047800",
    "type": "advancedmind_error",
    "code": "insufficient_credits"
  }
}

Credits are checked first

Before any provider is contacted, the gateway verifies your API key, that the key is scoped to the model, and that your credit balance can cover the estimated cost. If any of these checks fails, the request is rejected with the matching code, no inference runs, and nothing is charged. Add credits and retry.

Status codes

Code	HTTP	When it happens	What to do
`invalid_api_key`	401	The bearer token is missing, malformed, or has been revoked.	Check the Authorization header and create or rotate a key.
`insufficient_credits`	402	Your organization cannot cover the estimated cost of the request. Checked before any provider call, so no inference runs.	Top up credits, then retry.
`research_access_required`	403	The request selected a research or premium-research model without an active entitlement naming that model.	Apply for Research Mode, then use a research-scoped key after the model is explicitly approved.
`model_not_allowed`	403	The API key is valid but is not scoped to the requested model.	Update the key's allowed models, or use a key that includes this model.
`context_length_exceeded`	400	The prompt plus max_tokens exceeds the model's context window.	Trim the input or lower max_tokens.
`margin_guardrail_blocked`	409	Provider cost for this route changed and the route is held while pricing is refreshed, to protect the published price.	Choose another model now; the route returns once pricing settles.
`rate_limited`	429	You exceeded the request rate allowed by your plan.	Back off and retry after a short delay. New plan upgrades are paused during Preview.
`provider_unavailable`	503	The upstream provider for this route is down or not accepting traffic.	Choose another model or retry shortly. No usage is charged.
`model_disabled`	503	The selected model has no currently enabled, release-qualified route.	Choose another model or retry after the release is available. No usage is charged.
`provider_timeout`	504	The provider accepted the request but did not respond in time.	Retry. A request whose terminal status is timed_out is not charged; only a completed request settles at its accepted catalog price.

Access and approval errors

research_access_required means the organization lacks a current entitlement naming the selected model for a request made under Research Mode. Ordinary standard Klara preview calls do not need this entitlement. Apply for an approved Research Mode scope. model_not_allowed means the API key itself is not scoped to that model; fix the key under API keys. A separate 503 still applies when an approved model is disabled or its exact release is unhealthy.

Provider and pricing errors

provider_unavailable (503), provider_timeout (504), and margin_guardrail_blocked (409) are transient and route-specific. Treat them as retryable: switch to another model immediately, or back off and retry the same route. For provider_timeout, a request whose terminal status is timed_out is not charged; only a completed request settles at its accepted catalog price. margin_guardrail_blocked means provider cost moved and the route is paused so the published price stays accurate; it returns on its own.

Retry guidance

Retry on 429, 503, and 504 with exponential backoff. Do not blindly retry 400, 401, 402, 403, or 409: these need a fix on your side before the call can succeed. Log the request_id so a failed call can be traced in your usage records.