Error codes.

The Execution Layer never returns a prose-only error. Every failure is one of 42 structured codes an agent can branch on and a person can act on. The authoritative registry is error-codes.json in the product; the codes are grouped below by kind.

Request: the call was malformed or ambiguous

Code	Meaning
INVALID_ARGUMENT	An argument is missing or the wrong type.
SCHEMA_VIOLATION	The payload failed the fail-closed schema check.
FIELD_UNKNOWN	A field named in the call does not exist on the model.
FIELD_REQUIRED	A field required for AI writes was not provided.
AMBIGUOUS_TARGET	A human reference matched more than one record; candidates are returned.
UNRESOLVED_REFERENCE	A human reference matched no record.
IDEMPOTENCY_KEY_REQUIRED	A write was sent without its idempotency key.
LIMIT_EXCEEDED	A read or export exceeded the allowed size.

Policy: the action was not allowed

Code	Meaning
MODEL_FORBIDDEN	The model is out of scope for this bundle or connection.
FIELD_FORBIDDEN	The field is hidden or read-only for MCP.
PERMISSION_DENIED	Odoo’s own access rules deny it for this user.
TOOL_NOT_AVAILABLE	The tool is not in this user’s bundle.
ACTION_NOT_ALLOWLISTED	The execute_action method is not on the allowlist.
PRECONDITION_FAILED	A declarative business rule was not satisfied.
APPROVAL_REQUIRED	A risk-classed action was staged; a person must approve it.
APPROVAL_PENDING	The approval request exists and is awaiting a decision.
APPROVAL_STALE	The payload changed after approval; the token is invalid.
APPROVAL_DENIED	A person declined the action.
EXPORT_DISABLED	Export is off for this bundle.
RATE_LIMITED	A per-key or per-user rate limit was hit.

State: the world did not match

Code	Meaning
MODEL_NOT_FOUND	The model does not exist.
TARGET_NOT_FOUND	The target record does not exist.
CONSTRAINT_VIOLATION	An Odoo constraint rejected the change.
ASSERTION_FAILED	An only_if assertion did not hold.
IDEMPOTENCY_CONFLICT	The same key was reused with a different payload.
PARTIAL_RESULT_REFUSED	A partial result was refused rather than returned as complete.
BATCH_ITEM_FAILED	An item in an atomic batch failed; the batch rolled back.
VERIFICATION_FAILED	The post-commit read did not match the declared intent.
CONTEXT_DEGRADED	The Context Layer is degraded; the pipeline continued without it.

Messaging: the send was not allowed to leave

New with governed messaging in version 1.1:

Code	Meaning
MESSAGING_DISABLED	Messaging is off globally, or this user’s level is Off.
CONFIRMATION_REQUIRED	The send is staged: the exact preview and a one-time token came back, and nothing was sent.
CONFIRMATION_STALE	The payload changed after the preview, or the token expired or was reused; nothing was sent.
NOT_A_MEMBER	The user is not a member of the target conversation.
MENTION_NOT_ALLOWED	The @mention target is not a member, or @everyone is off.
WHATSAPP_NOT_AVAILABLE	Odoo’s WhatsApp app is not installed, no account is configured, or the feature is off.
WHATSAPP_WINDOW_CLOSED	A free-form reply was attempted outside the open 24-hour window; templates remain available.
TEMPLATE_NOT_APPROVED	The WhatsApp template is not Meta-approved, inactive, or restricted.
TEMPLATE_VARIABLES_INVALID	The template’s variables were missing or malformed.

Server: something went wrong underneath

Code	Meaning
TIMEOUT	The operation exceeded its time budget.
COMMIT_FAILED	The transaction could not commit.
AUDIT_UNAVAILABLE	In strict mode, the audit write failed, so the call failed.
INTERNAL	An unexpected internal error.

What a refusal returns

Every refusal, including a denial, is audited and returns a structured object with the machine code, a detail payload (for example the candidate list on AMBIGUOUS_TARGET), a human sentence, and, where the fix is a policy change, a fix_location pointing at the bundle or precondition to adjust.

See troubleshooting for what to do about the common ones.