Skip to content
API · Idempotency

Idempotency-Key for safe retries

Avoid duplicate charges when your bot has to retry a request.

Why it matters

When your integration POSTs to a state-mutating endpoint and the request drops mid-flight — timeout, flaky network, transient 502 — you don't know for sure whether the operation applied. Blindly retrying can create two orders for the same cart or duplicate a recharge. The Idempotency-Key header solves this: send a unique key on the first attempt and any retry with the same key returns the original result without re-executing the mutation.

Supported endpoints

  • POST /external/orders
  • POST /external/customers/:id/wallet/recharge
  • POST /external/customers/by-phone/:phone/wallet/recharge
  • POST /external/inventory/licenses

On other endpoints the header is ignored. For inbound webhooks, the receiver must deduplicate using X-Nuvlyx-Event-Id.

How to use the header

curl -X POST https://api.nuvlyx.com/api/v1/external/orders \
  -H "Authorization: Bearer nvl_live_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: bot-wa-order-9f8e2a1b" \
  -d '{ "customerPhone": "+573001234567", "items": [...] }'

Key rules

  • Unique string per operation. Prefer UUIDv4 or a business-id prefix.
  • Max 80 characters.
  • Valid for 24 hours; freed afterwards.
  • Same key with a different body returns 409 Conflict.

Note

Full Idempotency-Key support is rolling out — some endpoints honor it now, others silently ignore it. This page is the contract we're moving toward. Write your integration as if it's already active; when we ship it you won't need to change anything.