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

> [card] [Arc settlement](https://docs.copby.digitalcop.shop/settlements.md)
>
> Review settlement stages and delivery boundaries.

> [card] [API reference](https://docs.copby.digitalcop.shop/api-reference)
>
> Inspect response schemas and endpoint-specific status codes.


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