Idempotência

Faça retries com segurança usando o header Idempotency-Key — chaves reservadas antes da execução, replays de chamadas bem-sucedidas por 24 horas, o header Idempotent-Replayed e IDEMPOTENCY_CONFLICT.

Um timeout ou uma conexão caída pode perder a resposta de uma decisão que rodou. Tentar de novo às cegas a rodaria — e cobraria — duas vezes. Envie um Idempotency-Key e um retry recebe a resposta guardada.

Idempotency-Key: lead-8421

A chave tem de 1 a 128 caracteres de A–Z a–z 0–9 . _ : -. Qualquer outra coisa falha com 400 INVALID_REQUEST.

Comportamento

SituaçãoO que acontece
Chave novaA chave é reservada para esta requisição antes de a decisão rodar. Se a decisão der certo (200), a resposta é guardada por 24 horas.
Mesma chave, mesma requisição, dentro de 24 horasA resposta guardada é devolvida com o header Idempotent-Replayed: true — o mesmo execution_id, as mesmas respostas, as mesmas entradas de destinos. A decisão não roda de novo, nada é cobrado, nada é entregue e nenhuma execução é registrada.
Mesma chave, mesma requisição, enquanto a primeira ainda está rodando409 IDEMPOTENCY_CONFLICT com Retry-After: 1 — "A request with this Idempotency-Key is still running. Retry in a moment to get its response." Tente de novo depois de um segundo: quando a primeira requisição terminar, você recebe a resposta guardada dela. A decisão nunca roda duas vezes.
Mesma chave, requisição diferente, dentro de 24 horas409 IDEMPOTENCY_CONFLICT sem Retry-After — "This Idempotency-Key was already used with a different request body." — mesmo enquanto a primeira requisição está rodando.
Mesma chave depois de 24 horasTratada como uma chave nova.
A primeira requisição falhouA reserva é liberada, então um retry com a mesma chave roda a decisão de novo.
A primeira requisição recebeu o fallback por erro de engine (action_reason.type = "engine_error")A reserva também é liberada: um retry com a mesma chave chega de novo ao engine — e os destinos disparam de novo, com novos IDs de entrega.
A primeira requisição nunca terminou — o servidor parou no meio da execuçãoA reserva expira depois de 2 minutos; aí a chave pode rodar de novo.

"Mesma requisição" significa o mesmo slug, o mesmo state e o mesmo valor de query include. O estado é comparado depois do parsing do JSON: espaços em branco não importam, mas a ordem das chaves importa — {"a":1,"b":2} e {"b":2,"a":1} são requisições diferentes. Monte o body do mesmo jeito em toda tentativa.

Escolhendo chaves

Use uma chave por operação lógica e reutilize-a nos retries dessa operação:

  • o ID da coisa sobre a qual você está decidindo: lead-8421, ticket:9f2c1d, msg_01HZX3…;
  • ou um UUID gerado uma vez quando a operação começa — não um por tentativa.

As chaves valem no escopo da API key que as enviou: o mesmo Idempotency-Key usado com uma chave live e com uma chave test são duas chaves diferentes.

Exemplo

# First call: runs the decision.
curl -i -X POST https://api.dcision.io/v1/decisions/spam-detection \
  -H "Authorization: Bearer $DCISION_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: msg-20261005-0042" \
  -d '{ "state": "Congratulations! You won a $1000 gift card, click here to claim now." }'

# Same call again: replayed.
# HTTP/1.1 200 OK
# Idempotent-Replayed: true

Enviar a mesma chamada de novo enquanto a primeira ainda está rodando devolve 409 com Retry-After: 1; tente de novo depois de um segundo para receber a resposta dela:

409 Conflict — ainda rodando
{
  "error": {
    "code": "IDEMPOTENCY_CONFLICT",
    "message": "A request with this Idempotency-Key is still running. Retry in a moment to get its response.",
    "request_id": "req_Hn5Wq2Lk8Tz1Vb4Xc7Pm"
  }
}

Enviar um estado diferente com msg-20261005-0042 dentro de 24 horas devolve:

409 Conflict
{
  "error": {
    "code": "IDEMPOTENCY_CONFLICT",
    "message": "This Idempotency-Key was already used with a different request body.",
    "request_id": "req_Fw2Lk9Tq7Mz1Vb6Xc3Pn"
  }
}

Bom saber

  • Os replays vêm primeiro. Um replay é devolvido mesmo que a decisão tenha sido publicada de novo ou desativada desde então: você recebe exatamente o que a primeira chamada devolveu, incluindo o version dela.
  • Os replays contam para o rate limit, como qualquer requisição autenticada.
  • Duplicatas simultâneas são seguras. A chave é reservada antes de a decisão rodar, então duas requisições enviadas ao mesmo tempo com a mesma chave nunca rodam as duas — nem cobram, nem entregam: a segunda recebe 409 com Retry-After: 1, e o retry dela recebe a resposta guardada. Os SDKs esperam e tentam de novo sozinhos.
  • Erros liberam a chave. A chave é verificada logo depois da autenticação, do rate limit e do body: qualquer falha posterior — uma decisão desconhecida ou desativada, a cota, um estado inválido, um erro de engine — a libera, e a próxima tentativa começa do zero.
  • Por sub-workspace. Com o header Dcision-Workspace, o sub-workspace de destino faz parte da requisição: a mesma chave usada para dois clientes é um conflito 409, nunca a resposta guardada do outro cliente.
  • As respostas guardadas contêm as respostas da decisão. Elas ficam guardadas por 24 horas, seja qual for a configuração storeOutput da decisão; o estado em si não é guardado para idempotência.
  • Os SDKs e a CLI fazem isso por você. Os SDKs enviam um Idempotency-Key em toda chamada decide e o reutilizam nos retries; dcision decide gera um quando você não passa nenhum e tenta de novo uma vez em erros de rede — veja CLI.

Veja Retries idempotentes para um cliente completo em JavaScript e Python.

Nesta página