> ## Documentation Index
> Fetch the complete documentation index at: https://crm-social.exuratech.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors and recovery

> Interpret error codes and define safe CRM actions.

Error responses use this format:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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. |

## Retry classification

| 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. |

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

## Webhook receiver errors

| 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.

> [card] [Previous: Idempotency](https://crm-social.exuratech.com/reliability/idempotency.md)
>
> Review how to retry movements.

> [card] [Next: Endpoint reference](https://crm-social.exuratech.com/reference/endpoints.md)
>
> Review the CRM API summary.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.