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-8421A chave tem de 1 a 128 caracteres de A–Z a–z 0–9 . _ : -. Qualquer outra coisa falha com 400 INVALID_REQUEST.
Comportamento
| Situação | O que acontece |
|---|---|
| Chave nova | A 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 horas | A 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á rodando | 409 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 horas | 409 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 horas | Tratada como uma chave nova. |
| A primeira requisição falhou | A 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ção | A 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: trueEnviar 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:
{
"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:
{
"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
versiondela. - 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
409comRetry-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 conflito409, 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
storeOutputda 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-Keyem toda chamadadecidee o reutilizam nos retries;dcision decidegera 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.
Rate limits
Limites de requisições por workspace em cada plano, janelas separadas para decisões e leituras, os headers X-RateLimit em toda chamada, Retry-After no 429 e como fazer backoff.
Limites
Todos os limites de tamanho e de quantidade num só lugar — corpo da requisição, estado e orçamento de tokens, decision schema, destinos e entregas, identificadores, workspace, time e login.