Skip to content
vokse.
Browse the reference
Back to the API reference
Guide

Idempotency

Mutating requests can be made safe to retry by sending an Idempotency-Key. If a request is lost to a timeout, replaying it with the same key returns the original result instead of creating a duplicate.

The Idempotency-Key header

Send a unique key (a UUID is ideal) on every POST, PUT or PATCH. The server stores the result keyed by it for 24 hours and replays that result on any retry with the same key.

The rules

  • Generate one fresh key per logical operation, before the first attempt.
  • Reuse the same key for retries of that exact operation.
  • Reusing a key with a different body returns IDEMPOTENCY_KEY_REUSED, never silent corruption.
  • GET requests ignore the header. Most DELETE routes accept it too, so retried deletes stay safe.

Example

Creating a transaction with a key: replaying the call returns the same transaction, not a second one.

bash
curl -H "Authorization: Bearer vokse_sk_…" \     -H "Content-Type: application/json" \     -H "Idempotency-Key: 7c2f9b1e-4a8d-4e3a-9c1b-2f6e8d0a1b3c" \     -X POST https://api.vokse.ai/households/current/transactions \     -d '{"accountId":"01J8ME9AZ2K3W7X4V5T6R7Q8S9","date":"2026-06-22","amountCents":-4250,"currency":"EUR","payeeName":"Mercadona"}'