Errors and recovery

Error responses use this format:

{
  "detail": "Error description"
}

Common cases

Code	Common cause	Recommended action
`401`	Missing or invalid API key.	Verify the secret and Bearer header; do not retry indefinitely.
`403`	Unauthorized origin or credential, or an action not permitted across branches.	Check permissions, the IP allowlist, and branch assignment.
`404`	User, wallet, or wallet account does not exist.	Run SSO with `create_wallets: true` or review the reference.
`409`	Insufficient balance, idempotency conflict, or state incompatible with the branch.	Do not complete the action; identify the cause before retrying.
`422`	Invalid payload, missing required field, or unregistered external branch.	Correct the request or synchronize the branch; this is not a transient error.
`5xx`	Temporary service failure.	Retry with backoff while preserving the same movement key.

Type	Retry	Condition
Timeout or disconnection	Yes	Same payload and same `idempotency_key`.
`429`	Yes	Honor `Retry-After` when present.
`5xx`	Yes	Exponential backoff and an attempt limit.
`401`, `403`, `404`, `422`	Not automatically	Requires correcting state, permissions, or payload.
`409`	It depends	Distinguish insufficient funds from an idempotency conflict.

Include a CRM correlation reference in your logs, but never record the API key, passwords, or SSO tokens.

CRM response	Expected behavior
`2xx`	ExuraCopy considers the event delivered.
`408`, `425`, `429`	ExuraCopy schedules another attempt.
`5xx`	ExuraCopy schedules another attempt.
Other `4xx`	Treated as a permanent rejection and requires review.

Do not return 2xx before persisting the event. If downstream processing is asynchronous, store it first and respond afterward.

Review how to retry movements.

Review the CRM API summary.