Errors

Errors use the standard envelope — see Response envelope. Branch on error.code (and, on the auth and limit failures, the finer error.subcode), never on the message text. Every error body also carries a requestId (returned as the X-Request-Id header too) — a safe, non-secret correlation id you can quote to support to find the exact failed request.

Codes and statuses

error.subcode

The auth, access, and rate-limit failures carry a stable error.subcode next to error.code and error.requestId — a finer discriminator within a code, so you can tell two UNAUTHORIZEDs apart without matching the human message (which may be reworded). It is additive: present on the rows below, absent on every other error, and the code/status never move.

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "subcode": "key_disabled",
    "message": "API key is disabled.",
    "requestId": "9f3b7d4c2a61"
  }
}

What you can hit on v1 today

v1 is a full read-write surface, so most of the table is live:

• UNAUTHORIZED — key problems, including a key you disabled yourself.
• FORBIDDEN — API access off for the workspace (api_access_disabled), a missing scope (Missing required scope: <scope>. — see Scopes), or an owner-protected target (for example, changing the workspace owner's member row).
• NOT_FOUND — the resource does not exist in your workspace; another workspace's ids read identically to unknown ones.
• VALIDATION_ERROR — a rejected body or parameter on any write.
• USAGE_LIMIT_REACHED — a plan cap on creation endpoints (chatbots, sources, seats, reseller client seats) or an out-of-credit state.
• FILE_TOO_LARGE / UNSUPPORTED_FILE_TYPE — the knowledge file upload.
• RATE_LIMITED — the per-plan per-workspace budget or the per-IP flood guard, or an endpoint's own stricter one (exports, crawl, topics, domain verification). See Rate limits.
• INTERNAL_ERROR — rare, and worth reporting.

The chatbot and domain codes (CHATBOT_INACTIVE, DOMAIN_NOT_ALLOWED, AI_PROVIDER_ERROR) belong to the widget's public endpoints and are listed here because one client library usually handles all of them.

Dashboard-session codes

These five exist in the same catalogue and never appear on /api/v1:

They describe the state of a signed-in user session or the dashboard login flow, and API keys have neither. In particular, when a workspace owner is suspended or deleted, v1 does not return ACCOUNT_SUSPENDED — it returns the ordinary access-gate 403 with "API access is not enabled for this workspace." (api_access_disabled), so a key holder cannot detect a moderation action.

Handling them

async function apiGet(path) {
  const res = await fetch(`https://app.evoriqa.com/api/v1${path}`, {
    headers: { Authorization: `Bearer ${process.env.EVORIQA_API_KEY}` },
  });
  const body = await res.json();
  if (body.success) return body.data;

  switch (body.error.code) {
    case "RATE_LIMITED":
      throw new RetryableError(body.error.message); // back off and retry
    case "FORBIDDEN":
      throw new Error("API access is off for this workspace — check the gate.");
    default:
      throw new Error(`${body.error.code}: ${body.error.message}`);
  }
}

Retry RATE_LIMITED with backoff and INTERNAL_ERROR sparingly. Do not retry UNAUTHORIZED or FORBIDDEN — nothing about them changes on a second attempt.

Where to go next

• Rate limits
• Authentication