BroadRouter
Começar

Chave de idempotência (idempotency key)

Atualizado em

Uma chave de idempotência é um valor único, normalmente um ID aleatório como um UUID, que o cliente anexa a uma requisição que altera estado, como um pagamento ou uma compra. Se a mesma requisição for enviada de novo com a mesma chave, o servidor retorna o resultado original em vez de executar a ação duas vezes.

Também chamado de: chave de idempotência, idempotência em API, requisição idempotente, retry idempotente, idempotency key, Idempotency-Key header, idempotency token, idempotent request, idempotent retry

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.

Perguntas frequentes

Quando devo gerar uma nova chave de idempotência?

Só para uma nova ação pretendida. Reutilize a mesma chave em todas as novas tentativas de uma ação, e não crie outra até saber o resultado da primeira tentativa.

Requisições de chat completion para um LLM precisam de chave de idempotência?

Gerar texto não tem efeito colateral duradouro, então uma requisição de chat repetida normalmente só custa tokens de novo. A chave importa para chamadas que cobram dinheiro ou criam recursos. A BroadNet a documenta apenas para a compra de chaves por hora, não para chat completions.

O que acontece se eu reutilizar uma chave com um corpo de requisição diferente?

O draft da IETF diz que o servidor deve rejeitá-la com 422 Unprocessable Content, porque a chave já está associada a outra requisição.

Ler em MarkdownPerguntar ao ChatGPTPerguntar ao ClaudePerguntar ao Perplexity