Idempotency

All write operations (POST) require an Idempotency-Key header. This guarantees that retrying a request after a network failure never creates duplicate transfers.

How it works

1. Send a request with a unique Idempotency-Key
2. If the request succeeds, nuez stores the response for 24 hours
3. If you resend the same request with the same key, nuez returns the stored response — no duplicate operation

curl -X POST https://api.nuez.app/v1/transfers \
  -H "Authorization: Bearer nz_sk_live_..." \
  -H "Idempotency-Key: invoice-2026-04-23-001" \
  -H "Content-Type: application/json" \
  -d '{"amount": 5000, "destination": "proveedor.empresa"}'

Choosing a key

Use a value that is:

• Unique per operation — not per request. Two requests for the same logical payment should use the same key.
• Deterministic — derive it from your business data: invoice-{id}, order-{id}-payment, etc.
• Not reused across different operations — different payments must use different keys.

Caution

If you reuse the same key for two different transfers (different amount or destination), the second request returns the original response — the new parameters are ignored. Always use a unique key per distinct payment.

Idempotency window

Keys are stored for 24 hours. After that, a request with the same key is treated as new.