Docs · Guides

Error reference

What each code means, whether it may be retried, and what to do about it.

How to read this

Every response carries a request_id. Quote it in support. The Retry? column is the important one, and it is not advice about politeness — retrying something marked “never” can perform an action twice.

Decisions and authorization

Code	Meaning	Retry?	What to do
policy_no_match	No rule matched the request.	No	Add a rule, or accept the refusal.
policy_requires_approval	A person must decide.	No	Wait for the approval; do not proceed.
policy_not_configured	The project has no active version.	No	Publish and activate one.
risk_requires_approval	Risk raised the bar.	No	Wait for the approval.
risk_denied	Risk refused it outright.	No	Investigate the agent.
permit_invalid / revoked	The permit does not verify, or was revoked.	No	Issue a new permit.
action_not_covered	The permit does not cover this action.	No	Widen the permit — deliberately.
resource_not_covered	The permit does not cover this resource.	No	Same.
attenuation_violation	A delegated permit tried to widen.	No	Delegation can only narrow.
usage_limit_exceeded	A permit counter is spent.	No	A new window or a new permit.
agent_frozen	The agent is stopped.	No	Release it, if that is right.
unsupported_constraint	The permit carries a constraint this build cannot enforce.	No	Refused rather than ignored, on purpose.

Execution

Code	Meaning	Retry?	What to do
execution_unknown	The action may or may not have happened.	Never	Establish what happened, then resolve it.
execution_failed	The other side refused. Nothing happened.	Yes, with a new nonce	Fix the cause.
execution_in_progress	A concurrent execution is in flight.	Wait	Do not send a second nonce for the same action.
execution_invalid	The execution block is malformed.	No	Check the fields — `url` is not one of them.

Credentials, access and transport

Code	Meaning	Retry?	What to do
api_key_missing / malformed	No usable key on the request.	No	Send `authorization: Bearer bk_…`.
api_key_unknown / revoked	That key is not valid.	No	Mint a new one in the Console.
role_required	Your roles do not include this operation.	No	ADMIN is not every role — that is deliberate.
forbidden	Authenticated, not permitted.	No	Check the role table.
session_missing / invalid	The console session is absent or expired.	No	Sign in again.
csrf_missing / invalid	A mutation arrived without a matching token.	No	Echo the CSRF cookie.
rate_limited	Too many requests.	Yes, later	Back off.
project_not_found	No such project — or not yours.	No	Same answer a typo gets, on purpose.

Signing and dependencies

Code	Meaning	Retry?	What to do
signing_unavailable	Custody refused or could not be reached, before signing.	Yes	Nothing was signed.
signing_unknown	Custody may have signed.	Never	Hold it for a person.
audit_unavailable	The audit trail could not be written.	Depends	A decision is recorded as degraded rather than silently unlogged.
revocation_unavailable	The revocation registry could not be consulted.	Yes	Not treated as “not revoked”.
database_unavailable	A datastore is down.	Yes	Nothing was decided.

Anything named *_unknown means the operation may have happened. Those are the only codes in this document that must never be retried automatically.