A rede falha no pior lugar: depois que o servidor agiu, mas antes de você receber a resposta. Uma chave de idempotência torna a nova tentativa segura.
Como funciona
O cliente cria uma chave única para uma ação pretendida e a envia com a requisição. O servidor guarda a chave junto com o resultado. Se a mesma chave chegar de novo, o servidor devolve o resultado guardado em vez de agir outra vez.
O grupo de trabalho HTTPAPI da IETF está padronizando isso como o header de requisição Idempotency-Key (draft 08, outubro de 2026, ainda não é um RFC). Ele descreve a chave como “a unique value generated by the client which the resource uses to recognize subsequent retries of the same request” (tradução: um valor único gerado pelo cliente, que o recurso usa para reconhecer novas tentativas da mesma requisição) e recomenda um UUID ou um ID aleatório semelhante. Os casos de erro do draft:
| Situação | Status |
|---|---|
| Chave ausente onde é obrigatória | 400 Bad Request |
| Requisição original ainda em andamento | 409 Conflict |
| Chave reutilizada com outro corpo | 422 Unprocessable Content |
A Builders’ Library da AWS diz o mesmo do lado do cliente: “APIs with side effects aren’t safe to retry unless they provide idempotency.” (tradução: não é seguro repetir chamadas a APIs com efeitos colaterais, a menos que elas ofereçam idempotência).
Por que importa
Novas tentativas com backoff exponencial são prática padrão, e muitos SDKs repetem automaticamente. Sem idempotência, uma nova tentativa depois de um timeout pode criar dois pedidos ou duas cobranças. Com uma chave, repetir é seguro, seja qual for o resultado da primeira tentativa. Por isso ela é uma ferramenta central para agentes e scripts que compram, reservam ou criam coisas sem um humano acompanhando.
Na BroadNet Inference
A BroadNet usa esse padrão na compra de chaves por hora. POST /portal/keys/hourly recebe um request_id no corpo JSON, e a documentação afirma que “Idempotency is required for money safety” (tradução: a idempotência é necessária para a segurança financeira):
curl -X POST https://inference.broadnet.ai/portal/keys/hourly \
-H "Authorization: Bearer <portal-credential>" \
-H "Content-Type: application/json" \
-d '{"request_id":"order-20260920-001","label":"kiosk-1"}'
Reutilizar um request_id não cria nem cobra outra chave. Depois de um timeout, de uma conexão interrompida, de um 409 mint_in_progress ou de um 5xx, tente de novo com o mesmo request_id. Uma repetição retorna already_issued: true e o alias da chave; só a primeira resposta bem-sucedida contém a chave em texto puro. A documentação diz: “Never generate a replacement id until the original result is known.” (tradução: nunca gere um id substituto antes de saber o resultado original).
A BroadNet não documenta chave de idempotência para /v1/chat/completions nem para transcrições. Veja códigos de erro e novas tentativas para saber o que repetir nesses casos, e rate limit para entender por que novas tentativas às cegas podem piorar um 429.