Idempotency

Network calls can fail after the server has already acted. An idempotency key lets you retry a write without performing it twice. The first request does the work, and every retry with the same key returns the original result.

How it works

Send an Idempotency-Key header on any write request. Use a unique value per logical operation, for example a UUID you generate before the first attempt. The server records the key with the result of the first request. If you send the same key again, the server returns the stored result instead of acting a second time.

curl -s https://sandbox-api.xkova.com/v1/payments \
  -H "Authorization: Bearer xkv_test_..." \
  -H "Idempotency-Key: 5f3c0b8e-2a1d-4c9f-9b7a-1e2d3c4b5a6f" \
  -H "Content-Type: application/json" \
  -d '{ "...": "..." }'

What counts as the same request

An idempotency key is tied to the request it first completed. Reusing the same key with a different body is a conflict, rejected with 409 and the idempotency_conflict error code. Keep one key for one intended operation, and generate a fresh key for a genuinely new operation.

Telling a replay apart

A replayed request returns the same cached response as the original, plus two headers so your logging and monitoring can tell it apart: Idempotent-Replay: true marks the response as a replay, and X-Original-Correlation-Id carries the correlation id of the original request the cached response came from.

When to use it

Always send an idempotency key on writes that move money or create resources, so a timeout or a dropped connection cannot cause a double send. Reads do not need one, because they do not change state.

Related

See Errors and Correlation IDs for how to tell a retryable failure from a permanent one, and the interactive reference for which operations accept an idempotency key.