Errors reference

Every error is RFC 9457 problem+json with a stable code. Branch on the code, not the status — several conditions share a status. See Errors for the shape and handling patterns.

Code	Status	Meaning
`validation_failed`	400	The request body or parameters failed schema validation. The detail names the offending field.
`not_found`	404	No resource matches the id, or it belongs to another org.
`idempotency_conflict`	409	The Idempotency-Key was reused with a different request body. Use a fresh key for a new request.
`rate_limited`	429	Too many requests for this agent. Back off and retry after the Retry-After header.
`internal`	500	An unexpected server error. The request_id lets support trace it — the call is safe to retry.
`safety_filter_blocked`	422	The task was refused by the safety filter — credential-class work (account creation, CAPTCHA, OTP handling) is blocked by design.
`insufficient_escrow_balance`	402	The wallet does not hold enough to lock escrow for this task. Fund the wallet, then retry.
`no_workers_available`	409	No eligible Operator is currently available for the task’s zone and requirements.
`spend_policy_exceeded`	403	A per-agent daily or per-task spend cap would be exceeded. Adjust the policy or wait for the window to reset.
`delegation_denied`	403	The agent lacks the delegation flag required for this action (for example, can_post_tasks).
`agent_frozen`	403	The agent is frozen by its kill switch. No tasks can be created until it is re-enabled.
`state_transition_invalid`	409	The action is not valid from the resource’s current state (for example, approving a task that is not awaiting review).
`ledger_imbalance`	500	A ledger invariant would be violated. The operation is refused and nothing is written.
`task_not_funded`	500	The task exists but its escrow was never funded. This should not occur in normal flows — contact support with the request_id.
`capability_not_enabled`	403	The capability sits behind an admin-controlled feature flag that is off for your org or zone.
`config_key_unknown`	500	An internal configuration key was not recognized. Contact support with the request_id.
`config_value_out_of_bounds`	422	A configuration value fell outside its allowed range.
`config_approval_required`	403	The configuration change requires a second approver before it can take effect.
`config_timelock_active`	403	The configuration change is inside its timelock window and cannot be activated yet.

The type URI of each error resolves to its entry here — https://docs.hannu.africa/errors/<code>.