Errors and resilience

Odoo errors often contain useful framework or business messages. Log them with a request correlation ID, but redact API keys and sensitive record values.

Response classes

Status	Meaning	Retry policy
400 / 422	Invalid domain, field, parameter, or business validation	Fix the request; do not retry unchanged
401	Invalid or expired API key	Rotate credentials; do not loop
403	Access right or record-rule denial	Review permissions; do not retry automatically
404	Route, model, method, or record unavailable	Verify runtime metadata and environment
409	Conflicting state or concurrent operation	Re-read state, then retry deliberately
429	Capacity or explicit rate control	Back off using server guidance
5xx	Server or infrastructure failure	Retry bounded, idempotent operations with jitter

Error object

{
  "name": "odoo.exceptions.AccessError",
  "message": "You are not allowed to access this document.",
  "arguments": ["You are not allowed to access this document."],
  "context": {},
  "debug": "Traceback ..."
}

Do not expose debug tracebacks to end users. They can reveal module paths and implementation detail.

Retry rules

• Retry reads after transient network and 5xx failures.
• Retry creates only with an application-level idempotency key or unique external reference.
• Do not automatically retry a timed-out mutation unless you can determine whether Odoo committed it.
• Use exponential backoff with jitter and a strict maximum attempt count.
• Place failed business operations in a reviewable queue rather than retrying forever.

Observability

Record the environment, model, method, duration, HTTP status, correlation ID, and a safe business identifier. Never log bearer tokens or full financial payloads by default.