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.
`captcha_required`	400	A bot challenge is armed on this endpoint and no challenge token was supplied. Render the challenge and retry with its token.
`captcha_failed`	403	The challenge token was rejected as invalid, expired or already used. Render a fresh challenge and 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_operators_available`	409	No eligible Operator is currently available for the task’s zone and requirements.
`zone_unavailable`	422	The zone can’t take this task at this time (not serviceable, or the deadline is before the earliest feasible / after the latest / on a blackout or outside operating hours). The problem carries the remedy — earliest_available, next_open, suggested_deadline, alternative_zones. Don’t blind-retry; adjust and re-post.
`zone_temporarily_unavailable`	503	The zone is temporarily unavailable (paused or over capacity). Retry after the Retry-After header.
`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.
`platform_sandbox`	403	A money-committing action was refused because the organization is not live-eligible — either the business is not yet verified, or live money is switched off platform-wide. The detail names the remedy.
`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).
`duplicate_business`	409	That business registration number is already in use on another verified account. A registered business is a single identity here; contact support if you believe this is wrong.
`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.
`session_invalid`	401	The credential is missing, unrecognized, expired or revoked. Authenticate again and retry — this is distinct from a 400, which means the request itself was malformed and should not be retried unchanged.
`identity_provider_unavailable`	503	Our identity-verification provider is unreachable or unusable. This is our upstream problem, never a statement about the person being verified. Transient — retry.

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