Errors

Kordio Control has two kinds of failure and they are not the same thing. A refusal is a policy answer with a full decision in the body. An error is a request that could not be evaluated at all.

A denial is not an error

A denied decision answers 403 and carries the whole decision, not just a code:

403 Forbidden

{
  "data": { "id": "9b2ef0c1-6a3d-4e75-8c19-2f4b7d5a0e63", "state": "denied" },
  "decision": {
    "outcome": "denied",
    "rule": "per_transaction_cap",
    "detail": { "limit_cents": 50000, "requested_cents": 120000 },
    "headroom": { "session_remaining_cents": 380000, "per_action_cap_cents": 50000 },
    "policy_snapshot": [
      {
        "id": "a05f8c37-6b12-4d94-8207-c3e1b9d6a4f8",
        "status": "active",
        "mode": "blocklist",
        "imports": [],
        "per_transaction_cap_cents": 50000,
        "velocity_cap_cents": null,
        "velocity_window_seconds": null,
        "monthly_cap_cents": null,
        "approval_threshold_cents": null,
        "counterparty_allowlist": [],
        "rules": []
      }
    ]
  }
}

headroom is measured before the reservation, so on an allowed decision it still counts the amount you were just authorized to spend. policy_snapshot is the policy as it read at that instant, which is what lets a decision be re-read months later against a rule that has since changed.

A 403 from the agent API is a policy answer, not a transport failure. Do not retry it with a fresh idempotency key: that asks the same question again and, for a held action, asks a person twice. Change the action or change the policy.

Rules that can refuse

decision.rule names what decided. Rules created through the typed policy columns report under the column’s name, not the underlying kind. See the mapping table.

`decision.rule`	Why
`no_policy`	The agent has no active policy, so nothing is authorized for it yet.
`session_inactive`	The budget is not `active`. Nothing in the API moves a budget out of `active` today, so in practice a budget that has run out denies with `session_budget` instead.
`runtime_scope`	The agent key is not scoped for this `action_type`.
`session_budget`	The action does not fit the remaining budget envelope.
`per_transaction_cap`	Over the per-action ceiling set by `per_transaction_cap_cents`.
`velocity_cap`	Over the rolling-window cap set by `velocity_cap_cents`.
`monthly_cap`	Over the calendar-month cap set by `monthly_cap_cents`.
`counterparty_allowlist`	The counterparty is not on `counterparty_allowlist`.
`cost_cap`	Over a `cost_cap` rule written in the `rules` array.
`spend_window`	Over a `spend_window` rule written in the `rules` array.
`monthly_spend_cap`	Over a `monthly_spend_cap` rule written in the `rules` array.
`rate_limit`	Too many actions in the window, regardless of amount.
`action_allowlist`	This action type is not permitted.
`resource_allowlist`	This resource is not permitted.
`not_allowlisted`	An allowlist-mode policy matched no `allow` rule.
`spend_token_unusable`	The token is not `issued`, or has expired.
`spend_token_ceiling`	The amount exceeds the token’s ceiling.
`spend_token_counterparty`	The token is pinned to a different counterparty.

A rule written with a custom rule_name reports under that name instead. An approval_threshold never appears as a denial. It does not refuse; it answers 202 and holds the action. See holding spend for a person.

What `detail` carries

decision.detail is keyed by the rule that decided, not by a shared schema. Read it by rule:

Rule	`detail` keys
`no_policy`	`message`
`session_inactive`	`status`
`runtime_scope`	`action_type`, `scopes`
`session_budget`	`remaining_cents`, `requested_cents`
`cost_cap`, `per_transaction_cap`	`limit_cents`, `requested_cents`
`spend_window`, `velocity_cap`	`limit_cents`, `window_seconds`, `projected_cents`
`monthly_spend_cap`, `monthly_cap`	`limit_cents`, `projected_cents`
`rate_limit`	`limit`, `window_seconds`, `projected`
`approval_threshold`	`threshold_cents`, `requested_cents`
`action_allowlist`	`action_type`, `allowed`
`resource_allowlist`, `counterparty_allowlist`	`resource`, `allowed`
`not_allowlisted`	`policy_id`
A `condition` rule	`rule_id`, `matched`
`spend_token_unusable`	`status`
`spend_token_ceiling`	`ceiling_cents`, `requested_cents`
`spend_token_counterparty`	`pinned`, `requested`

The amount ceilings report limit_cents, not max_cents, and the approval threshold reports threshold_cents, not above_cents. Those are the names you wrote the rule with, not the names it answers with. An allowed decision has rule: null and detail: {}. Nothing decided it; nothing refused.

Error envelope

Everything that is not a decision returns:

{ "error": { "message": "Agent is not scoped for tool.invoke", "code": null } }

Switch on code where it is present. message is for humans and may change. code is null for most validation failures; only the codes below ever set it. Branch on the HTTP status first and treat code as a refinement, not as the primary signal.

Codes

runtime_key_required

401 - No agent key was presented. Send Authorization: Bearer krt_....

invalid_runtime_key

401 - The key was not recognised, or its agent is suspended or revoked.

identity_token_required

401 - No dashboard token was presented on a /control/v1/workspaces/* or /v1/account call. Agent keys do not reach these routes; send a WorkOS access token.

invalid_identity_token

401 - The dashboard token was rejected: malformed, expired, or signed by something this environment does not trust.

budget_ceiling

422 - The budget asked for is larger than the agent’s max_budget_cents, which is set from the dashboard and cannot be raised with an agent key. The body carries ceiling_cents and requested_cents so the caller can open a smaller one rather than guess.

parent_budget_exhausted

422 - A child budget was asked for that is larger than the parent has left. Children reserve from their parent when they are opened, so several children cannot sum past it. ceiling_cents is what the parent actually has left.

insufficient_role

403 - Your membership does not carry the capability this call requires. Approving needs approve; writing policy and managing agents need manage_policy; members and billing need manage_members.

idempotency_conflict

409 - A request with this Idempotency-Key is still in flight, so there is no stored response to replay yet. Wait and retry with the same key; do not mint a new one.

idempotency_key_required

422 - POST /control/v1/agent/actions requires an Idempotency-Key header. Note the status: this is a 422, not a 400.

POST /control/v1/agent/payment_intents does not use that header. It requires an idempotency_key field in the body, and its absence is a 400. The two authorize endpoints are asymmetric here.

authorization_required

400 - POST /control/v1/cosign/verify was called with no token, in neither the authorization body field nor an Authorization header.

rate_limited

429 - Back off per the Retry-After header. Agent endpoints allow 1200 requests per minute per key; workspace endpoints allow 300.

billing_unavailable

503 - Billing could not be reached, so a call that had to check entitlement could not be answered. Authorization is unaffected; retry.

identity_unavailable

503 - The identity provider could not be reached during sign-in.

identity_not_configured

503 - This deployment has no identity provider configured.

mfa_required

401 - Sign-in needs a second factor. The response carries pending_authentication_token and authentication_challenge_id alongside error; complete at POST /v1/auth/verify_mfa.

email_verification_required

401 - The account exists but its email is unverified. The response carries pending_authentication_token; complete at POST /v1/auth/verify_email.

invalid_signature

401 - An inbound billing webhook failed HMAC verification.

Statuses without a code

Status	When
`400`	A required body parameter is missing.
`404`	The budget, intent or workspace does not belong to you. Kordio does not confirm existence across a tenancy boundary, so this is a `404` rather than a `403`.
`422`	The request was understood but cannot be applied: a rule that would not compile, an import naming an unknown module, an intent resolved from the wrong state, a module still imported by a policy.
`500`	Unexpected. Retry; if it persists, contact support.

Get started

Core concepts

Guides

Guarantees

Reference

Endpoints

A denial is not an error

Rules that can refuse

What `detail` carries

Error envelope

Codes

runtime_key_required

invalid_runtime_key

identity_token_required

invalid_identity_token

budget_ceiling

parent_budget_exhausted

insufficient_role

idempotency_conflict

idempotency_key_required

authorization_required

rate_limited

billing_unavailable

identity_unavailable

identity_not_configured

mfa_required

email_verification_required

invalid_signature

Statuses without a code

Next steps

How a decision is reached

Writing a policy

​A denial is not an error

​Rules that can refuse

​What detail carries

​Error envelope

​Codes

​runtime_key_required

​invalid_runtime_key

​identity_token_required

​invalid_identity_token

​budget_ceiling

​parent_budget_exhausted

​insufficient_role

​idempotency_conflict

​idempotency_key_required

​authorization_required

​rate_limited

​billing_unavailable

​identity_unavailable

​identity_not_configured

​mfa_required

​email_verification_required

​invalid_signature

​Statuses without a code

​Next steps

How a decision is reached

Writing a policy

A denial is not an error

Rules that can refuse

What `detail` carries

Error envelope

Codes

runtime_key_required

invalid_runtime_key

identity_token_required

invalid_identity_token

budget_ceiling

parent_budget_exhausted

insufficient_role

idempotency_conflict

idempotency_key_required

authorization_required

rate_limited

billing_unavailable

identity_unavailable

identity_not_configured

mfa_required

email_verification_required

invalid_signature

Statuses without a code

Next steps