> ## Documentation Index
> Fetch the complete documentation index at: https://docs.copby.digitalcop.shop/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors and lifecycle

> Handle API errors, idempotency, retries, and settlement fund states.

Treat transport failures, validation errors, and lifecycle outcomes differently. Never infer that
funds moved from an HTTP timeout alone.

## HTTP handling

| Status         | Action                                                       |
| -------------- | ------------------------------------------------------------ |
| `400`          | Fix the request; do not retry unchanged input                |
| `401` or `403` | Fix credentials or organization access                       |
| `404`          | Check the resource ID and organization                       |
| `409`          | Reuse the existing idempotent resource or requote            |
| `422`          | Route or amount is not executable; request a new quote later |
| `429`          | Retry with backoff                                           |
| `500` or `503` | Preserve the idempotency key and reconcile before retrying   |

## Idempotency

Use one stable `Idempotency-Key` per logical payout or settlement order. A network retry uses the
same key. A new customer action uses a new key.

## Settlement errors

Settlement errors include `stage`, `fundsStatus`, `fundsMoved`, `retryable`, and `nextAction`.
Follow those fields instead of parsing the human-readable message.

```json theme={null}
{
  "error": {
    "code": "QUOTE_EXPIRED",
    "message": "La cotizacion expiro.",
    "stage": "CREATED",
    "fundsStatus": "IN_USER_WALLET",
    "fundsMoved": false,
    "retryable": true,
    "nextAction": "CREATE_NEW_QUOTE"
  }
}
```

`health: STUCK` does not replace the order status. It means the order needs recovery while the
status and `fundsStatus` continue to describe the last verified state.

## Safe retry rule

Before resubmitting an onchain action, check the stored resource and transaction receipt. Never
create a second burn, swap, or payout merely because the first HTTP request timed out.

<Columns cols={2}>
  <Card title="Arc settlement" icon="bridge" href="/settlements">
    Review settlement stages and delivery boundaries.
  </Card>

  <Card title="API reference" icon="square-terminal" href="/api-reference">
    Inspect response schemas and endpoint-specific status codes.
  </Card>
</Columns>