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.

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.