Error taxonomy

When a gateway call fails, you receive the error as a uniform JSON envelope:

{
  "error": {
    "code": "validation_error",
    "message": "Params violate the capability input schema.",
    "hint": "Call describe(id) and resend params matching input_schema.",
    "retryable": false,
    "audit_id": "audit_123"
  }
}

Error codes

Code	Meaning for agents
validation_error	Input does not match the schema; read describe and correct
auth_required	Bearer key is missing or invalid
scope_missing	Key does not have the required scope
not_found / version_not_found	Check ID or version
not_implemented	visible in catalog, but not invocable
dry_run_required	first send a successful dry_run with the same parameters
precondition_failed	business precondition is missing, do not blindly retry
conflict	Target state conflicts, read again and decide
rate_limited	Observe retry_after_seconds
budget_exceeded	Clarify wallet, budget or policy
capability_disabled	Kill switch or capability lock is active
approval_required / approval_rejected	Handover or human decision needed
upstream_error	external/connected service did not respond cleanly
internal_error	retry later; if it recurs, provide audit ID to support

Response rule

retryable: true does not mean “spam immediately”. Retry with backoff, the same idempotency key and the same intent. With retryable: false, first change the cause or hand over to a human.

HTTP 412 in onboarding

HTTP 412 precondition_failed in the initial path is expected behavior when a business precondition is still missing.

Endpoint	When 412 is expected	Response
GET /org/current	before owner claim or, if agent_email is set, before agent email verification	complete the missing OTP step, then use again as a status read
POST /keys/rotate	before owner claim or before required agent email verification	complete the initial path; do not replace a lost key by re-bootstrapping
POST /mcp/dry_run	before required OTPs or before operator approval	poll /org/current until operator_approval_status is approved
POST /mcp/invoke	before required OTPs or before operator approval	do not operate; apply polling or handover rule

Response: Wait for the owner code, call POST /owner-otp/claim and if agent_email is set, additionally verify POST /agent-otp/verify. Afterwards, repeat /org/current as a status read. If operator_approval_status remains pending for a long time, follow the troubleshooting.

Next

Budgets & kill switch