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

# Errors and idempotency

> Retry safely, handle errors reliably, and follow the rules for a production-ready integration.

Follow these rules across your whole integration. They prevent duplicate resources, brittle error handling, and data that drifts out of sync.

## Idempotency and retries

Use a stable `external_reference` from your own system for every profile and account, and use it to match records.

| Request | Safe to retry? |
| - | - |
| `POST /kyc/profiles` | Yes. A retry with the same `external_reference` and email returns the existing profile. |
| Other create and write requests | Only if that endpoint's documentation says so. Otherwise, [look the resource up first](https://docs.gnosispay.com/platform-integration/operations/reconciliation.md#find-existing-resources). |

Process webhooks idempotently too. Use the event `id` to skip events you've already handled.

## Handle errors

Branch your code on the stable error `reason`, not the human-readable `message`. The message is for people and can change at any time.

## Treat changes as asynchronous

Assume creation and status-changing operations finish asynchronously, unless the endpoint explicitly says otherwise. Wait for a webhook or read the resource before treating a change as done. When ordering matters, read the current state of the resource instead of relying on the order events arrive in.

## Represent amounts exactly

Many financial and token amounts are strings paired with a `decimals` value. Keep them as strings or use a decimal library. Don't convert them to floating-point numbers, which lose precision.

## Keep secrets out of logs

Never log credentials, access tokens, or sensitive card data. See [Handle sensitive card data](https://docs.gnosispay.com/platform-integration/cards/sensitive-cards.md) for the full list of safeguards.

## Before going live

Test the complete lifecycle in sandbox, from onboarding to card transactions and reconciliation, before you request production access. See [Sandbox vs Production](https://docs.gnosispay.com/platform-integration/configuring-environment.md).


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