Idempotência e Novas Tentativas

Toda chamada de tempo real deve carregar um Idempotency-Key. Não é uma cortesia de limite de taxa — é o que torna uma nova tentativa segura. As redes falham depois que o fornecedor já foi acionado; sem uma chave, a única forma de descobrir se uma verificação foi executada é executá-la de novo e pagar por ela duas vezes.

A regra

Envie um valor que você consiga regenerar: um UUID, um ID de pedido ou um hash do trabalho que você está fazendo. O servidor o restringe à sua conta, então dois usuários não podem colidir.

Mesma chave	Payload	Resultado
Chave nova	qualquer	Executa normalmente, com cobrança
Mesma chave	idêntico	A resposta armazenada é retornada; replayed=true. Nenhuma cobrança nova.
Mesma chave	diferente	409 idempotency_conflict — uma chave fica vinculada ao payload que carregou primeiro
Mesma chave	idêntico, primeira chamada ainda em execução	409 request_in_progress com Retry-After

Idempotency-Key é limitado a 191 bytes e os registros de reprodução são mantidos por 30 dias por padrão.

replayed não é cached

Eles parecem semelhantes em uma resposta e significam coisas diferentes:

Campo	Onde	Significa
replayed	nível superior	Esta chamada nunca chegou a um fornecedor — você reproduziu uma chave.
cached	dentro de cada resultado	O veredito deste produto veio do cache de resultados.

Uma chamada reproduzida devolve a resposta original, incluindo o valor de cached de cada entrada. Nenhum dos dois sinalizadores altera o que foi cobrado: uma reprodução nunca movimenta dinheiro, e um acerto de cache continua sendo cobrado pelo preço por verificação do produto.

Apenas resultados liquidados são armazenados como fatos. Resultados com falha e unknown não são armazenados em cache — uma verificação posterior do mesmo identificador no mesmo produto consultará o fornecedor de novo em vez de reproduzir uma resposta inconclusiva.

Tentar novamente após uma falha

O que você viu	O que fazer
Timeout, ou HTTP 500	Reenvie o corpo original com a chave original. O resultado é incerto; é para este caso que a chave existe.
409 request_in_progress	Aguarde Retry-After e então reenvie o mesmo corpo com a mesma chave.
409 idempotency_conflict	A chave já carrega um payload diferente. Gere uma nova chave — não edite o corpo e reutilize a antiga.
429 realtime_rate_limited	Aguarde Retry-After. Nada foi enviado, então a mesma chave ainda está livre e é seguro enviá-la.
503 realtime_route_unavailable	Nada foi enviado. Tente novamente mais tarde, com a mesma chave.

A única coisa que você nunca deve fazer após um timeout é enviar uma chave nova com o mesmo trabalho: se a primeira chamada chegou, você acabou de pagar duas vezes pela verificação.

Erros gerados aqui

HTTP	code
400	idempotency_key_required — cabeçalho ausente
409	request_in_progress — a chamada original ainda está em execução
409	idempotency_conflict — a chave foi usada pela primeira vez com um payload diferente