Idempotency

POST /v1/withdraws requires an Idempotency-Key header — this is the only REST endpoint that enforces it, and the request is rejected with 400 MISSING_IDEMPOTENCY_KEY if it’s missing. This guarantees that retrying a request after a network failure never creates a duplicate payout.

(The equivalent MCP tool, request_payout, and several card/bill tools take the same concept as a required idempotency_key argument in the request body instead of a header — see MCP tools.)

How it works

1. Send a request with a unique Idempotency-Key. Internally it’s hashed together with your user ID (sha256(user_id + ":" + key)), so the same literal key used by two different users never collides.
2. If the request succeeds, nuez stores the exact response body for 24 hours.
3. If you resend the same request with the same key, nuez returns the stored response verbatim — no new payout attempt is created, no policy re-evaluation happens.

curl -X POST https://sandbox-api.nuez.app/v1/withdraws \
  -H "Authorization: Bearer <jwt>" \
  -H "Idempotency-Key: invoice-2026-04-23-001" \
  -H "Content-Type: application/json" \
  -d '{"amount_ars": 5000, "destination": "0000003100010000123456", "destination_kind": "CBU"}'

Choosing a key

Use a value that is:

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

Caution

If you reuse the same key for two different payouts (different amount or destination), the second request returns the original response — the new parameters are silently 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 and creates a fresh payout attempt.