Errors

This is the one reference for errors. It covers the shapes a failure can take, the codes you will see, and what to do about each. Paging and idempotency are in Pagination and errors; the 429 budgets are in Rate limits.

Error codes at a glance

Every error.code the public API returns, in one line each. The sections below carry the detail. Branch on the HTTP status first (see the shapes), then on code.

These come back as HTTP 200 with success: false, so branch on success, not on the status:

Three operations report a failure in another field, also with HTTP 200. messages.optimize returns ok: false with a reason (optimizer_timeout, optimizer_error, optimizer_unconfigured); see When ok is false. agents.resume returns status: "not_found", "invalid_state" or "invalid_input", and agents.cancel returns status: "not_found" or "cannot_cancel"; see Agents. Over MCP a refusal can also be isError text, such as invalid_uri on a URI read or insufficient_scope.

Check the status before you read error

Failures do not all share one shape, and error is not always an object. An error handler written against the object shape alone reads body.error.code as undefined on the string-shaped bodies, which fails silently: it will not recognise an expired key. Branch on the HTTP status first, then on code.

1. Operation refusals: 4xx, inside the data envelope. The request reached an operation, and the operation refused it. success is false and the typed error sits beside it:

{
  "data": {
    "success": false,
    "error": {
      "code": "invalid_argument",
      "message": "Unknown filter field \"not_a_field\" on surface \"deals\". Known fields: deal_id, …",
      "details": { "field": "not_a_field", "surface": "deals" }
    }
  }
}

2. Gate and schema errors: bare envelope. The request was refused before an operation ran (a missing scope, an off-surface operation, a body that failed schema validation) or the operation threw. There is no data wrapper:

{
  "error": {
    "code": "invalid_input",
    "message": "Input failed schema validation",
    "details": {
      "errors": [{ "path": "$.limit", "message": "must be <= 200", "value": 500 }]
    }
  }
}

• code: a stable machine-readable string. Branch on it.
• message: a human-readable description. Safe to log and show. Do not pattern-match on it; the text can change.
• details: optional, and its shape depends on the code. Present only when the server has something structured to attach.

3. Authentication and routing failures: 401 / 404, bare, and error is a string. These short-circuit ahead of the typed handler, so they carry no code and no details:

{
  "error": "Unauthorized",
  "message": "Valid OAuth token or API key required. Send an API key as \"Authorization: Bearer <key>\" or \"X-API-Key: <key>\"; send an OAuth token as \"Authorization: Bearer <token>\"."
}

An unmatched route returns 404 in the same string shape with no message. Treat both as terminal from the status alone.

The global per-IP limiter's 429 is a fourth shape: a plain-text body, not JSON. See Rate limits.

Codes

Three more codes belong to one call each:

• invalid_sql (400) on a warehouse read: the SQL the gate refused must change. Retrying is pointless.
• over_cap on POST /evals/export: more than 5,000 rows matched. It comes back as success: false inside the data envelope with HTTP 200, so branch on success. See Export runs.
• mixed_eval_versions (400) on a training-data export: the filter spans more than one eval version. See Export runs as training data.

Per-operation codes

Some operations define richer codes on top of the set above. They use the same envelope; only the code is more specific.

agents.resume (POST /agents/:session_id/resume)

A resume answers 200 and reports a failure in status, not in error.code:

The agent library (/agents CRUD)

Authoring (POST /evals, PATCH /evals/:slug)

validation_failed carries the exact field errors when a definition fails the authoring checks. POST /evals/validate returns the same errors as { valid: false, errors: [...] } without storing anything.

Search (search.query, search.fields)

Past parameter validation Search does not use error envelopes for degradations. Every partial outcome is a typed field on a success: true result (detail.internal.status, corpus.empty_reason, coverage: null). The error codes it returns are invalid_argument, the warehouse-read codes above, and the gate codes. One case to know: on the plain-language (fuzzy) lane, running out of the warehouse-read budget comes back as 200 with detail.internal.status: "failed", not as a 429. See Rate limits.

setup_needed: the workspace has nothing connected

setup_needed means the workspace has no connected source (no CRM, no call recorder), so there is nothing for the call to read. It has one reason, no_sources_connected, and it comes in two forms. Both carry the same field:

The hint: 200, not an error. search.query answers an empty result with success: true, and adds setup_needed beside results. A count over nothing is one row of zeros ([{ "count": 0 }]) and carries it too. research.start, evals.run, messages.optimize (with evidence: "workspace") and the accepted messages.optimize_batch (when an item asks for evidence: "workspace") add the same field to a success when the work still goes ahead.

{
  "data": {
    "success": true,
    "mode_ran": "fuzzy",
    "results": [],
    "setup_needed": {
      "reason": "no_sources_connected",
      "message": "This workspace has no data connected yet, so there is nothing to search. Connect your CRM or call recorder at https://console.amdahl.ai/acme/settings/connections, then ask again.",
      "connect_url": "https://console.amdahl.ai/acme/settings/connections"
    }
  }
}

The refusal: 409. When the workspace also holds no conversation themes, research.start and an evals.run that could only end not_applicable (empty_corpus) are refused before any quota is counted. No job starts. The refusal is shape 1: error.code is setup_needed, error.details holds reason and connect_url, and the full field rides beside error, so a client that already relays the hint relays this one with no new rule.

{
  "data": {
    "success": false,
    "error": {
      "code": "setup_needed",
      "message": "This workspace has no data connected yet, so there is nothing to search. Connect your CRM or call recorder at https://console.amdahl.ai/acme/settings/connections, then ask again.",
      "details": {
        "reason": "no_sources_connected",
        "connect_url": "https://console.amdahl.ai/acme/settings/connections"
      }
    },
    "setup_needed": {
      "reason": "no_sources_connected",
      "message": "This workspace has no data connected yet, so there is nothing to search. Connect your CRM or call recorder at https://console.amdahl.ai/acme/settings/connections, then ask again.",
      "connect_url": "https://console.amdahl.ai/acme/settings/connections"
    }
  }
}

An eval run is not refused when it can grade without the workspace's conversations: with include_external: true, with evidence_from_run or candidate_from_run, or when the eval has a case of only rule or structure graders.

How to handle either form:

1. Check for the field first. Read setup_needed on every response from these calls, success or not. On the 409, error.code is setup_needed as well.
2. Show the user message and connect_url. Do not report "no results", and do not show a failure the user cannot act on. Connecting a source is the fix, and the link goes to the page that does it.
3. Do not retry until a source is connected. The same call answers the same way until then. Backoff does not help, and a retried search still counts as a search call.
4. Do not answer from your own knowledge. An agent must not fill the gap with general knowledge as if it came from the user's data. Say the workspace has nothing connected yet.

The field is absent when the workspace has a connected source (also one that is broken, or one that was disconnected after it synced), when rows came back, and when the server could not check. An empty search without it is an honest empty: read corpus.empty_reason. The field goes away on the next call after the first source connects; the data appears once that source's first sync lands. More in the FAQ and in Connections.

Read 404s name the shapes that ARE valid

When a URI-addressed read returns nothing, the error lists what the scheme does serve:

{
  "error": {
    "code": "not_found",
    "message": "Not found: eval_run://missing-run. Valid eval_run:// shapes: eval_run://<id>, eval_run://list, eval_run://<id>/report, eval_run://<id>/compare/<other_id>.",
    "details": {
      "valid_uri_shapes": [
        "eval_run://<id>",
        "eval_run://list",
        "eval_run://<id>/report",
        "eval_run://<id>/compare/<other_id>"
      ]
    }
  }
}

The URIs in this body use the registry spelling (eval_run://), which REST and the Anthropic read_resource tool accept. Over MCP, spell the two-word schemes with a hyphen (eval-run://): an underscore is illegal in a URI scheme, and standards-compliant clients throw on it before the request is sent. Both spellings resolve on the server.

You get the same body whether the row is missing or the id was never well-formed (GET /eval-runs/not-a-uuid). The two are deliberately indistinguishable, so a 404 cannot be used to probe whether an id is valid.

A URI whose scheme exists but whose sub-path nobody serves (eval_run://<id>/cases) is refused with invalid_uri rather than not_found, because the shape is wrong rather than the row missing. invalid_uri reaches you only on the URI-addressed surfaces (read_resource and MCP resources/read). Over REST an unserved path is an ordinary unmatched route.

details.valid_uri_shapes is scope-filtered: it lists only the shapes your credential may read, and is omitted when there are none. Treat it as a hint for correcting a request. operation://list is the authoritative catalog.

Security-sensitive errors

1. 404 instead of 403 for cross-tenant access. A Chat, eval run, routine or connection that exists but belongs to another workspace returns 404 not_found, so a caller cannot tell "does not exist" from "exists but not yours". If you are sure the id is yours and get a 404, check that your key is bound to the right workspace.
2. Masked secrets in error details. When a validation error touches a field the platform treats as sensitive (tokens, API keys, refresh credentials), details shows [MASKED] in place of the value.

Retry strategy

• Retry: 5xx (operation_error, internal_error, query_failed) and rate_limited. Use exponential backoff with jitter: start at 500 ms, double each attempt, cap at 30 seconds, give up after 5 attempts unless your workload can tolerate more.
• Honor Retry-After. When a 429 or 503 carries it (in seconds), wait at least that long. On a JSON 429, details.retry_after_seconds carries the same number.
• Do not retry any other 4xx. invalid_input, invalid_argument, forbidden, not_on_public_api, not_found, quota_exceeded and setup_needed all mean this exact call will not succeed, and retrying spends rate-limit budget on top of the original failure.
• Retrying a POST can create a duplicate. See Idempotency.

Request id

Every response carries an X-Request-Id header. Capture it when you log or surface an error; support requests that include it resolve faster.

You can also send X-Request-Id on the way in, and the platform uses your value instead of minting one, so you can correlate on an id your own system already assigned. It is echoed back on the response and exposed via CORS so browser clients can read it. Values are truncated to 128 characters and stripped of anything that cannot legally sit in a header, so send an id you generated, not user input. A UUID is the easiest id to join on: it is stored as sent, while any other value is stored in the audit trail under a fixed UUID derived from it.

See also

• Pagination and errors: paging, filters and idempotency
• Rate limits: the 429 budgets and backoff
• Authentication: 401 and 403 handling
• Agents: the resume and cancel state machine behind invalid_state