Skip to main content

Errors and troubleshooting

When a call fails, AION answers with an HTTP status code and, in most cases, a JSON body {"detail": "<code or message>"}. This page lists the errors you are likely to meet while integrating, what they mean and what to do. It is for developers and IT staff debugging an integration.

Authentication and permissions​

StatusdetailMeaningWhat to do
401api_key_invalid_formatThe key is malformed.Send the full key aion_<8>_<32>, without quotes or spaces.
401api_key_invalidNo such key.Check you copied the right key, for the right AION installation.
401api_key_revokedThe key was revoked.Create a new key.
401api_key_expiredThe key expired.Create a new key; plan rotation before expiry.
401api_key_owner_disabledThe owner's account or their API-key permission is disabled.Ask the administrator.
401otherNo credentials, or an expired login token.Send Authorization: Bearer <key> or X-Api-Key: <key>.
403api_key_not_allowedThis endpoint never accepts API keys (admin API, memory, credentials, settings, key management…).Use the chat app or admin panel for that task.
403missing_scopeThe key lacks the permission this endpoint needs.Create a key with the right permission.
403profile_not_allowed / model_not_allowedThe owner may not use that profile.Pick a profile from GET /profiles or ask the administrator.
403password_change_requiredThe owner has a temporary password.The user must sign in to the chat app and change it.

Requests and resources​

StatusMeaningWhat to do
400Invalid input, e.g. a conversation id with forbidden characters.Ids: letters, digits, -, _, 4–128 characters.
404Conversation, file or model not found — or it belongs to someone else (AION does not reveal other people's conversations).Check the id and that you are using the owner's key.
404 model_not_foundUnknown profile slug on the OpenAI-compatible API.Use an id from GET /v1/models.
422The JSON body does not match the schema (missing message, wrong type…).The response lists the invalid fields.

Limits and server problems​

StatusMeaningWhat to do
429Too many requests. Headers X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset tell you the limits.Slow down and retry after the reset time.
504The turn took longer than the allowed time (timeout_seconds on /v1/chat, AION_OPENAI_COMPAT_TIMEOUT_SEC on the OpenAI API).Raise timeout_seconds (up to 3600), use streaming, or split the task. The work may still be saved in the conversation.
503A required service (database, Redis, session storage) is unavailable.Ask the administrator to check the server health.

Errors inside a streamed answer​

On POST /v1/chat/stream the HTTP status is 200 once the stream starts; later problems arrive as events:

  • {"type": "error", "content": "…"} — the turn failed or was interrupted (cancellation, limits, model unreachable).
  • {"type": "llm_error", "code": "…", "message": "…"} — the AI model returned an error (for example wrong credentials or quota exceeded on the provider side): tell the administrator.
  • an event: error frame with {"error": "…", "code": "…"} — failure before the agent started, e.g. profile_not_found.

The end-of-turn rules are in Chat stream events.

Common problems​

The call hangs for minutes. It is probably working: the agent may be using many tools. Use streaming to see progress, and set client and proxy timeouts to at least 5–10 minutes.

The answer ignores the file I uploaded. With /v1/chat you cannot pass attachments; use /v1/chat/stream with attachments (see Conversations and files).

The agent doesn't remember the previous message. You did not send the conversation_id of the first call, so every call started a new conversation.

I see the conversations in the chat sidebar. That is expected: the key acts as you. Use a service account for integrations whose conversations should not appear in a person's sidebar.

Open the conversation in the chat app to see exactly what the agent did (tools, inputs, outputs): it is the fastest way to debug an unexpected answer.