Guia

Idempotência

Os pedidos que alteram dados podem tornar-se seguros de repetir com uma Idempotency-Key. Se um pedido se perder num timeout, repeti-lo com a mesma chave devolve o resultado original em vez de criar um duplicado.

O cabeçalho Idempotency-Key

Envie uma chave única (um UUID é ideal) em cada POST, PUT ou PATCH. O servidor guarda o resultado associado a essa chave durante 24 horas e devolve-o em qualquer nova tentativa com a mesma chave.

As regras

Gere uma chave nova por operação lógica, antes da primeira tentativa.
Reutilize a mesma chave nas repetições dessa operação exata.
Reutilizar uma chave com um corpo diferente devolve IDEMPOTENCY_KEY_REUSED, nunca corrupção silenciosa.
Os pedidos GET ignoram o cabeçalho. A maioria das rotas DELETE também o aceita, para que repetir uma eliminação continue a ser seguro.

Exemplo

Criar um movimento com uma chave: repetir a chamada devolve o mesmo movimento, não um segundo.

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"}'