Errors

Every error the platform returns follows the same envelope and the same handful of HTTP status codes. This page is the canonical reference: the envelope shape, the status-to-code mapping, and a recovery matrix you can implement against.

For rate-limit specifics see Rate limits. For pagination-specific error cases see Pagination and errors.

Canonical error envelope

All errors use this exact shape:

json

{
  "error": {
    "code": "invalid_input",
    "message": "Field 'task' is required.",
    "details": {
      "field": "task",
      "expected": "string"
    }
  }
}

Three fields:

code: stable machine-readable identifier. Safe to branch on.
message: human-readable description. Safe to log. Do not pattern-match against it programmatically; copy may change.
details: optional JSON object with structured context. Shape depends on the code. Present when the server has something useful to attach (offending field, rate limit window, violated constraint).

The envelope is consistent across REST and MCP surfaces. MCP tool error responses wrap the same object as the result of the tool call so you can branch on code identically.

HTTP status code mapping

HTTP status	Common codes	When it fires
400	`invalid_input`, `invalid_argument`, `validation_error`	The request body, query string, or tool input failed validation. Fix the payload and retry.
401	`unauthenticated`, `invalid_token`, `expired_token`	No credentials were presented, or the bearer token could not be parsed. Re-auth.
403	`forbidden`, `scope_denied`, `insufficient_role`	The caller is authenticated but lacks the required scope, role, or tenant membership. Grant the scope or upgrade the role.
404	`not_found`	The resource does not exist, or it exists but belongs to another tenant. See "Security-sensitive errors" below.
409	`conflict`, `duplicate`, `version_conflict`	The write would violate a uniqueness constraint or clobber a newer version of the resource. Read, merge, retry.
429	`rate_limited`	Rate limit exceeded. Back off and retry; see Rate limits.
500	`internal`, `server_error`	Unexpected server-side failure. Retry with backoff; file an issue if persistent.
503	`service_unavailable`, `dependency_unavailable`	An upstream dependency (database, Anthropic API, worker queue) is temporarily down. Retry with backoff.

Status codes are the primary signal for your client-side dispatcher; code is the secondary signal for precise handling.

Public-surface gate codes

Three codes gate the public API surface itself. They fire before any operation logic runs, so every endpoint can return them:

Code	Status	Meaning
`feature_disabled`	403	The workspace is not on Agent Platform v2 (the `agent_v2` flag is off), so the gated operation families refuse. Ask a workspace admin to enable it; see Endpoints: prerequisites.
`not_on_public_api`	403	The operation exists but is not part of the public surface for an external credential (API key or external OAuth token). Only the operations in the tool catalog are externally reachable; everything else serves the console only.
`quota_exceeded`	429	An operator-set monthly cap on a verb family (search / enrich / lookalike / evals) is exhausted for the workspace. `details` carries the family, the limit, and usage; the cap resets at the start of the next month.

feature_disabled and not_on_public_api are terminal for the credential — do not retry; quota_exceeded is terminal for the month unless the cap is raised.

Per-tool error codes

Some operations define richer codes on top of the standard set. They still use the canonical envelope; only the code value is more specific.

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

Code	Status	Meaning
`invalid_input`	400	Resume payload did not match `pending_input_schema`. `details.validation_error` has the mismatch.
`invalid_state`	409	Run is not in `awaiting_input`. `details.current_status` shows where it actually is.
`not_found`	404	Run id unknown, or belongs to another tenant.

The agent library (`/agents` CRUD)

Code	Status	Meaning
`slug_conflict`	409	An explicit `slug` on create collides with an existing agent (or shadows an Amdahl library agent). Pick another slug.
`locked`	409	The target is a code-defined Amdahl library agent; update / delete are refused.

The synchronous verbs (`search.query`, `enrich.`, `lookalike.`)

Past parameter validation the verbs do not use error envelopes for degradations — every partial outcome is a typed field on a success: true result (refresh_omitted, available: false, freshness.source, mode_ran). The only error codes they return are invalid_argument (a named bad field, operator, or identifier — e.g. a bare person name on enrich.person) and the gate codes above.

Check each operation's entry in the tool catalog and the API reference for the authoritative list of codes it emits.

Security-sensitive errors

Two behaviors are worth calling out because they can look like bugs:

404 instead of 403 for cross-tenant access. If you request an artifact, session, or webhook that exists but belongs to another business, the platform returns 404 not_found rather than 403 forbidden. This prevents probing, so a caller cannot distinguish "does not exist" from "exists but not yours". If you are confident the id is yours and you get a 404, check that your API key is bound to the correct business, not that the resource was deleted.
Masked secrets in error details. When a validation error touches a field that the platform classifies as sensitive (tokens, API keys, refresh credentials), details will show [MASKED] in place of the offending value along with a <field>_masked: true sentinel. The error message is still useful; the value is just never echoed back.

Recovery matrix

The client behavior that is right for each code class:

Code class	Retry?	Action
`invalid_input`, `invalid_argument`, `validation_error`	No	Fix the payload. The details field names the offending field. Do not retry the same request.
`unauthenticated`, `invalid_token`, `expired_token`	Yes, after re-auth	Run the auth flow to obtain a fresh credential, then retry. See Authentication.
`forbidden`, `scope_denied`, `insufficient_role`	No	The token is valid but lacks authority. Do not retry; surface to a human to grant the scope or role.
`not_found`	No (usually)	Validate the id. For cross-tenant 404s, verify the API key is bound to the correct business.
`conflict`, `duplicate`, `version_conflict`	Yes, after merge	Read the current state, reconcile, resubmit with the updated version number or dedupe key.
`rate_limited`	Yes, with backoff	Honor `Retry-After` or `details.retry_after_seconds`. Exponential backoff with jitter, capped at 60s. See Rate limits.
`internal`, `server_error`	Yes, with backoff	Retry up to 3 times with backoff. If the correlation id repeats, file an issue.
`service_unavailable`, `dependency_unavailable`	Yes, with backoff	Same as `internal`. These indicate transient upstream problems.

Correlation id

Every response carries an X-Correlation-Id header. When you surface errors to a user or log them for ops, capture the correlation id. On our side it joins the request to the audit log and any upstream traces. Support requests that include the correlation id resolve significantly faster.