Idempotência

Toda escrita (POST, PUT, PATCH) aceita o header X-Idempotency-Key. Com ele, repetir a mesma requisição (por um timeout, uma queda de rede, um retry automático) não cria nada duas vezes: a API devolve a resposta original.

curl -H "Authorization: Bearer $KOBANA_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: disparo-2026-10-31-baixa" \
  -X POST https://api.kadu.ia.br/v1/tasks/2f1c…/run \
  -d '{"environment_id":"8a40…","reference_date":"2026-10-30"}'

Regras

Regra	Valor
Formato da chave	texto opaco, de 1 a 255 caracteres
Validade	24 horas
Escopo	a organização: a mesma chave em organizações diferentes não colide
O que identifica a requisição	método, caminho, query e corpo

Situação	Resposta
Chave nova	a requisição roda normalmente, e a resposta fica guardada
Mesma chave, mesma requisição	a resposta original (status e corpo), com `X-Idempotent-Replay: true`
Mesma chave, requisição diferente	`409 IDEMPOTENCY_KEY_REUSED`
Mesma chave enquanto a primeira ainda processa	`409 IDEMPOTENCY_REQUEST_IN_PROGRESS`

Gere uma chave por operação de negócio (por exemplo, disparo-<data>-<tarefa>), e não por tentativa: é a mesma chave em todos os retries que torna o retry seguro.

O endpoint de disparo aceita o mesmo header, com as mesmas regras.

Regras​

Regras