Errors

Every failure returns the same shape, so you write one handler.

{
  "error": {
    "type": "invalid_request",
    "code": "assistant_not_published",
    "message": "This assistant is not published."
  },
  "request_id": "req_01HB"
}

Status codes#

Codes#

Authentication#

All four are 401, and none of them distinguishes further — telling a caller that a key used to exist is telling them something about your workspace.

Permission#

Not found#

Conflict#

Validation#

Service#

Errors during a stream#

Once a stream has started the status is already 200, so a later failure arrives as an event instead:

event: error
data: {"code":"api_error","message":"Something went wrong on our side."}

The stream closes after it. Whatever was generated up to that point is stored — the transcript records the partial turn rather than pretending it did not happen.

Handle both paths. A pre-stream failure is a status code; a mid-stream failure is an event.

Retrying#

async function withRetry<T>(run: () => Promise<T>, attempts = 3): Promise<T> {
  for (let attempt = 1; ; attempt++) {
    try {
      return await run();
    } catch (error) {
      const retryable =
        error instanceof ZeevaaError &&
        (error.status === 429 ||
          (error.status >= 500 && error.code === "api_error"));

      if (!retryable || attempt >= attempts) throw error;

      // Exponential, with jitter — without it, everything that failed
      // together retries together and the second wave is the same size.
      const wait = 2 ** attempt * 250 + Math.random() * 250;
      await new Promise((resolve) => setTimeout(resolve, wait));
    }
  }
}

Retrying a POST /sessions creates a second conversation, and retrying a /chat sends the message twice. Retry the whole turn only if the first attempt never reached us — a connection error rather than a response.

What errors never contain#

Model names, provider names, internal ids, stack traces, or the contents of another workspace. An error message is safe to log and safe to show; if you need more detail than it gives, request_id is what identifies the request to us.

Next#

• Rate limits — the 429 in detail
• Authentication — the 401s in detail