Errors

Implementation: DESIGN (server) · Exposure: PUBLIC PREVIEW (contract). The Agency API is not live yet. This page describes the published v0.3 contract so you can review and build against it; details may change before alpha.

Every 4xx and 5xx response has the same body: one error object.

{
  "error": {
    "family": "POLICY",
    "code": "ERR_POLICY_DENIED",
    "message": "Writing outside the workspace is not permitted by profile code-write@1.",
    "retryable": false,
    "request_id": "req_01J...",
    "run_id": "run_01J...",
    "param": null,
    "policy_reason_codes": ["fs.outside_workspace"],
    "receipt_id": "rcpt_01J...",
    "docs_url": "https://docs.allternit.com/api/agency/errors"
  }
}

Field	Meaning
`family`	The broad class of error. Branch on this.
`code`	The specific `ERR_*` code. Kernel codes pass through unchanged.
`message`	Human-readable text. Do not parse it.
`retryable`	Whether the same request may succeed if retried.
`request_id`	Quote this when you report a problem.
`run_id`	The run the error belongs to, if any.
`param`	The request field that caused the error, if any.
`policy_reason_codes`	Why policy denied or asked, for policy errors.
`receipt_id`	The receipt that recorded the denial or failure, if any.

The full field table is in Schemas: Error.

Handling codes you do not recognize

New codes may be added in a minor version. A client that meets an unknown code handles it by family and retryable, the same way it treats unknown enum values: as not understood, never as success.

retryable: true: retry with backoff, reusing the same Idempotency-Key. See Idempotency.
retryable: false: do not retry the same request. Fix the input, answer the attention request, or surface the error.

Errors that are never overridable

ERR_POLICY_DENIED (403) is a hard policy deny. It never becomes an approval request, and no answer, grant or score changes it. See Policy.
ERR_AUTHORITY_PROFILE_FORBIDDEN rejects any request that names a bypass-style profile.
ERR_DEFAULTS_UNRESOLVABLE means a safe value could not be resolved for an omitted field. No run executes; the API never falls back to a permissive default.
ERR_REPLAY_UNRECORDED fails one replay step whose external call has no recording. The call is never sent live. See Replay.

Reference

The tables below are generated from the v0.3 contract.

Error families

Family	Origin
`INPUT`	Kernel runtime
`STATE`	Kernel runtime
`CONTEXT`	Kernel runtime
`ROUTING`	Kernel runtime
`DECISION`	Kernel runtime
`TOOL`	Kernel runtime
`POLICY`	Kernel runtime
`MUTATION`	Kernel runtime
`VERIFY`	Kernel runtime
`TRANSFER`	Kernel runtime
`BUDGET`	Kernel runtime
`SYSTEM`	Kernel runtime
`AUTH`	API surface
`NOT_FOUND`	API surface
`IDEMPOTENCY`	API surface
`RATE_LIMIT`	API surface
`VERSION`	API surface

Error codes

Code	Origin
`ERR_APPROVAL_REQUIRED`	Kernel (passed through unchanged)
`ERR_ATTENTION_RESOLVED`	API surface
`ERR_AUTHORITY_PROFILE_FORBIDDEN`	API surface
`ERR_AUTH_INVALID`	API surface
`ERR_AUTH_SCOPE`	API surface
`ERR_COST_BUDGET`	Kernel (passed through unchanged)
`ERR_CURSOR_EXPIRED`	API surface
`ERR_DEFAULTS_UNRESOLVABLE`	API surface
`ERR_IDEMPOTENCY_IN_PROGRESS`	API surface
`ERR_IDEMPOTENCY_KEY_REUSED`	API surface
`ERR_INPUT_AMBIGUOUS`	Kernel (passed through unchanged)
`ERR_INPUT_UNSUPPORTED`	API surface
`ERR_NOT_FOUND`	API surface
`ERR_POLICY_DENIED`	Kernel (passed through unchanged)
`ERR_RATE_LIMIT`	API surface
`ERR_REPLAY_UNRECORDED`	API surface
`ERR_RUN_TERMINAL`	API surface
`ERR_STATE_CONFLICT`	Kernel (passed through unchanged)
`ERR_VERSION_UNSUPPORTED`	API surface
`ERR_WORKER_LOST`	Kernel (passed through unchanged)

Standard error responses

Response	Meaning
`ClientError`	Client error (standard envelope).
`Forbidden`	Policy or scope denies the action. Hard denies are never overridable.
`NotFound`	Resource does not exist or is not visible to the caller.
`Conflict`	State conflict, terminal state, attention already resolved, or idempotency conflict.
`Gone`	Event cursor is older than the retention window.
`Unprocessable`	Schema-valid but not compilable: ambiguous goal, unknown or forbidden profile, unknown criterion, or defaults that cannot be safely resolved (`ERR_DEFAULTS_UNRESOLVABLE`, never a permissive run).
`TooManyRequests`	Rate limit or admission cap reached.
`ServerError`	Server or kernel failure (standard envelope).

Platform API

Legal

Overview

Agency API (Preview)

LLM Gateway

Agents & Runtime

Work Queue & Deployments

Files, Webhooks & Sandbox

Tools & Connectors

Collaboration & Workflows

Infrastructure & Platform

Canvases

Onboarding

A Labs

Playground

Users & Profiles

Handling codes you do not recognize

Errors that are never overridable

Reference

Error families

Error codes

Standard error responses

​Handling codes you do not recognize

​Errors that are never overridable

​Reference

​Error families

​Error codes

​Standard error responses

​Related

Handling codes you do not recognize

Errors that are never overridable

Reference

Error families

Error codes

Standard error responses

Related