Novas tentativas seguras
Quando uma conexão cai, você não tem como saber se o pedido foi feito. Então envie de novo: por 7 dias, a mesma chave de idempotência significa o mesmo pedido, e ele é cobrado uma única vez.
Como funciona
POST /orders precisa de um cabeçalho Idempotency-Key: até 200 caracteres ASCII sem espaços, que você mesmo cria e guarda com seu próprio registro do pedido. Um UUID funciona bem. Use uma nova chave de idempotência para um novo pedido.
curl -X POST "https://api.talismanleads.io/v1/orders" \
-H "Authorization: Bearer tl_live_your_key_here" \
-H "Idempotency-Key: crm-export-2026-11-05" \
-H "Content-Type: application/json" \
-d '{"checker":"whatsapp_status_detection","entries":["+14155550142","+12125550187"]}'O que você recebe
201 e o novo pedido.200, o mesmo pedido e Idempotent-Replay: true. Nada mais é cobrado, mesmo que o preço tenha mudado desde então.order_status_unknown ou rate_limited.409 idempotency_conflict. Nenhum pedido é feito.insufficient_balance409 price_changed, e uma nova chave de idempotência faz o pedido pelo novo preço.Quando você não sabe
Qualquer resposta perdida, order_status_unknown e uma resposta que não é JSON, como um 502 ou 504 de um gateway, significam a mesma coisa: repita a requisição com a mesma chave de idempotência para saber o estado real. Isso nunca cobra duas vezes. Nunca crie uma nova chave de idempotência porque uma requisição atingiu o tempo limite ou falhou: isso é um novo pedido, e ele é cobrado.
Aguarde um minuto entre as repetições. Se ainda responder order_status_unknown depois de alguns minutos, pare e fale com o suporte informando o request_id. Não crie uma nova chave de idempotência.
Quanto dura uma chave de idempotência
Uma chave de idempotência é lembrada por 7 dias a partir do primeiro envio. Depois disso, a mesma chave faz um novo pedido, então repita em poucos dias e use uma nova chave de idempotência para cada novo pedido.