Pular para o conteúdo principal

Idempotência

A API suporta idempotência para repetir solicitações com segurança, sem executar a mesma operação duas vezes. Útil quando uma chamada é interrompida em trânsito e você não recebe resposta — por exemplo, uma requisição para criar uma conta a pagar que cai por erro de rede pode ser repetida com a mesma chave, garantindo que apenas um registro seja criado.

Como usar​

Envie o cabeçalho X-Idempotency-Key: <chave> em qualquer requisição POST, PUT ou PATCH. A chave é livre, gerada pelo seu lado. Recomendamos UUID v4 ou outra string aleatória com entropia suficiente para evitar colisões.

curl -i \
  -H "Authorization: Bearer $KOBANA_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'X-Idempotency-Key: 8c0f5d6e-3f8b-4cb5-9a47-d8f5b15e9b21' \
  -H 'User-Agent: Meu Sistema (contato@example.com)' \
  -d '{
    "account_id": "00000000-0000-0000-0000-000000000001",
    "description": "Aluguel Janeiro/2026",
    "amount": "3500.00",
    "due_date": "2026-01-10"
  }' \
  -X POST 'https://api.finance.kobana.com.br/v1/payables'

Como funciona​

Quando o servidor recebe uma requisição com X-Idempotency-Key:

  1. Reserva a chave atomicamente, escopada ao workspace. Dois workspaces diferentes podem usar a mesma chave sem conflito.
  2. Calcula a impressão digital da requisição — SHA-256 de método + caminho + corpo bruto. Esse hash é guardado junto com a chave.
  3. Executa o handler. Se ele retornar uma resposta, o servidor grava status_code, corpo e cabeçalhos relevantes vinculados à chave.
  4. Marca a chave como completa. Qualquer nova requisição com a mesma chave dentro de 24 horas recebe a resposta original verbatim — mesmo status_code, mesmo corpo, mesmos cabeçalhos — acrescida do cabeçalho X-Idempotency-Replayed: true para indicar que se trata de uma reexecução.

A camada salva o resultado independentemente de ter sido sucesso ou falha. Retries com a mesma chave retornam o mesmo resultado, incluindo erros 5xx.

Limites​

  • Tamanho máximo da chave: 255 caracteres.
  • Retenção: chaves expiram automaticamente 24 horas após a criação.
  • Escopo: por workspace. Uma chave usada em um workspace não interfere em outro.
  • Caracteres aceitos: qualquer string UTF-8 imprimível.

Conflitos​

Se a mesma chave for reutilizada com uma requisição diferente (qualquer mudança em método, caminho ou corpo), a API responde 409 conflict com details.reason = "idempotency_key_reused".

{
  "error": {
    "code": "conflict",
    "message": "X-Idempotency-Key was already used with different request parameters. Reuse the original parameters or generate a new key.",
    "details": { "reason": "idempotency_key_reused" }
  }
}

Métodos aceitos​

MétodoAceita X-Idempotency-Key?
POST✅ Sim
PATCH✅ Sim
GET❌ Não (já é idempotente por definição)
DELETE❌ Não (já é idempotente por definição)

Boas práticas​

  • Uma chave por operação lógica. Não reutilize a mesma chave para criar dois recursos diferentes — você receberá 409 conflict.
  • Persista a chave junto com o estado da operação no seu lado, para que o retry depois de crash ou reinício use a mesma chave.
  • Combine com backoff exponencial ao receber 5xx ou timeout.
  • Limpe a chave depois de 24 horas. Não há ganho em mantê-la no seu lado após esse prazo.