# Errors & Idempotency

How the API signals errors, the access-control codes to expect, and how to use idempotency keys safely.

## Error responses

The API uses standard HTTP status codes. A `2xx` status means success; `4xx` means the request was rejected; `5xx` means an unexpected server error. Errors return a machine-readable code you can branch on.

## Access-control errors

Product access is checked on every request. When a product is not enabled for your organization, you get a `403` with a specific code:

| Status | Code | Meaning |
|--------|------|---------|
| `403` | `banking_api_access_not_enabled` | Banking is not enabled for your organization's API access. |
| `403` | `cards_api_access_not_enabled` | Cards is not enabled for your organization's API access. |
| `403` | `api_access_disabled` | Checkout API access is not enabled for your organization. |

If you see one of these, ask your Dolafy contact to enable the product and the org-level API flag.

## Common resource errors

| Status | Code | Meaning |
|--------|------|---------|
| `404` | `banking_transfer_not_found` | No API-created transfer with that id exists for your organization. |
| `409` | `recipient_already_exists` | A recipient with the same PIX key already exists (unless replaying the same idempotency key). |
| `409` | `authorized_user_terms_required` | Card authorized-user terms must be accepted in the dashboard before issuing cards via the API. |
| `503` | `checkout_pix_not_available` | The organization is not set up to accept PIX for checkout yet. |

## Idempotency

Some write endpoints require an `Idempotency-Key` header so that retries never create duplicates:

- `POST /v1/banking/recipients`
- `POST /v1/banking/transfers`
- `POST /v1/cards`
- `POST /v1/checkout/products`
- `POST /v1/checkout/sessions`

For the checkout endpoints, the key must be 8–200 characters of letters, numbers, dots, underscores, colons, or hyphens.

**Your server generates the key.** Use a unique value for each new request. Reuse the exact same value **only** when retrying the same request after a timeout or network error — Dolafy will return the original result instead of performing the action twice.

```http
POST /v1/banking/transfers
x-api-key: dlfy_live_...
Idempotency-Key: pix-acme-1048
content-type: application/json
```

Guidelines:

- Derive the key from your own stable identifier for the operation (for example an invoice or order id).
- Do not reuse a key for a genuinely different request; that returns the original response, not a new one.
- Keys are stored on the created resource and reused for duplicate responses.