Errors

Every endpoint and every stream reports errors in the same shape, with a stable machine-readable code. Clients branch on the code, never on the message text or the HTTP status alone. This page is the reference.

Error formatCopy Anchor Link

{
  "error": {
    "code": "rate_limited",
    "message": "Too many messages. Try again in 18 seconds.",
    "retryable": true,
    "retry_after_ms": 18000,
    "trace_id": "7f3a9c2e5b1d",
    "details": {}
  }
}

In an SSE stream, the same object is sent as an error event, and the stream ends:

event: error
data: {"code":"provider_unavailable","message":"The AI service is temporarily unavailable.","retryable":true,"trace_id":"7f3a9c2e5b1d"}

If the stream has already started, the HTTP status is already 200. That is why the code inside the event, not the status, is the source of truth.

Error code referenceCopy Anchor Link

Request and authCopy Anchor Link

LimitsCopy Anchor Link

AI processingCopy Anchor Link

ToolsCopy Anchor Link

Documents and jobsCopy Anchor Link

ServerCopy Anchor Link

Writing error messagesCopy Anchor Link

Messages are shown to end users, so write them for end users.

The internal detail still matters for debugging. Put it in the logs under the same trace ID, never in the response.

Never leak through errorsCopy Anchor Link

Error paths are a common source of data leaks.

• No prompt content. A provider error can echo part of the prompt, including retrieved documents the user should not see in that form. Strip provider error bodies before building a response.
• No existence leaks. Return not_found for documents the user cannot access, the same as for documents that do not exist.
• No internal topology. Hostnames, service names, and stack traces stay in logs.
• No guardrail internals. Give a category such as "sensitive personal data", not the rule or classifier score, or attackers can tune their inputs against it.

Adding a new error codeCopy Anchor Link

1. Check whether an existing code fits. Prefer reusing over adding.
2. Add the code to the shared error definitions used by backend and frontend.
3. Add a user-facing message and action to the frontend's error mapping. See Error and empty states.
4. Add it to this page.
5. Add an alert if the code indicates a system problem rather than a user problem.

ChecklistCopy Anchor Link

• All endpoints and streams use the same error object.
• Clients switch on code, not on message text.
• retryable is accurate for every code.
• Messages are safe for end users, and internal details are only in logs.
• Provider error bodies are never passed through.
• not_found is returned for resources the user cannot see.