Errors.

A small, predictable error envelope. Here's how to read it, how to handle each class, and when to retry.

§ 01Error envelope

Every error response uses the same envelope as a successful one — same shape, just different fields populated. Read status first; if it is "error", look at the errors array for the specifics. The HTTP status code tells you the class.

{
  "request_id": "req_01HXYZABC123",
  "status": "error",
  "answer": "",
  "sources": [],
  "usage": { "tokens_in": 0, "tokens_out": 0, "latency_ms": 12 },
  "errors": [
    { "code": "INVALID_BODY", "message": "Field 'query' is required." }
  ],
  "upstream": {}
}

The errors array can carry more than one entry — for example, multiple validation failures on the request body. The first entry is the most important; clients can surface it directly to users.

§ 02HTTP status code reference

Every endpoint uses the same set of HTTP codes. Treat them as the primary signal for control flow; treat the errors array as the secondary, human-facing signal.

§ 03Common error codes

The code values inside the errors array are stable strings. Switch on them in code; surface message to humans.

§ 04Retry guidance

The API is idempotent for the data-plane endpoints — replaying a query produces a new run with a new request_id; it does not mutate previous state. That makes retries safe whenever the underlying error is transient. Two rules cover most cases.

When to retry

• Always on 429, 502, 504. These are transient by definition.
• Once on 500. After one retry, escalate.
• OK for cold-start retries on serverless lift-off — the first request to a freshly-deployed function may carry a one-off latency spike.

When not to retry

• Never on 400. The request itself is wrong; retrying will fail identically.
• Never on 401. The credential is invalid; rotate or refresh first.
• Never on 402. The plan limit is reached; retrying just consumes more attempts.

Exponential backoff

Use exponential backoff with full jitter. Start at 500ms, double on each attempt, cap at 16s, give up after 5 attempts. The combination handles every realistic burst the API will return.

async function withBackoff(fn, { attempts = 5, base = 500, cap = 16000 } = {}) {
  let last;
  for (let i = 0; i < attempts; i++) {
    try {
      return await fn();
    } catch (err) {
      last = err;
      const status = err.status ?? 0;
      const retryable = status === 429 || status === 502 || status === 504 || (status === 500 && i === 0);
      if (!retryable) throw err;
      const wait = Math.min(cap, base * 2 ** i) * Math.random();
      await new Promise(r => setTimeout(r, wait));
    }
  }
  throw last;
}