---
title: "O que é uma chave de idempotência? Retries seguros em APIs"
description: "Chave de idempotência: ID único criado pelo cliente e enviado na requisição para um retry não repetir o efeito, como cobrar 2 vezes. Como funciona e o header IETF."
url: https://broadrouter.com/pt/glossary/idempotency-key/
lang: pt-BR
updated: 2026-11-14
publisher: BroadRouter (a BroadNet site); API by BroadNet Inference, https://inference.broadnet.ai
---

Traduzido do inglês com ajuda de IA. [Leia o original em inglês](https://broadrouter.com/glossary/idempotency-key/) (atualizado em 2026-11-14).

# Chave de idempotência (idempotency key)

Atualizado em 2026-11-14

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](https://broadrouter.com/pt/glossary/exponential-backoff/) 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](https://broadrouter.com/pt/blog/hourly-llm-api-key-explained/). `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):

```bash
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](https://broadrouter.com/pt/guides/errors-and-retries/) para saber o que repetir nesses casos, e [rate limit](https://broadrouter.com/pt/glossary/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.

## Veja também

-   [Backoff exponencial (exponential backoff)](https://broadrouter.com/pt/glossary/exponential-backoff/) (termo)
-   [Rate limit (limite de taxa)](https://broadrouter.com/pt/glossary/rate-limit/) (termo)
-   [Chave de API (API key)](https://broadrouter.com/pt/glossary/api-key/) (termo)
-   [Concorrência (concurrency)](https://broadrouter.com/pt/glossary/concurrency/) (termo)
-   [Códigos de erro da BroadNet Inference e quando tentar de novo](https://broadrouter.com/pt/guides/errors-and-retries/) (guia)
-   [Restrinja chaves de API aos seus servidores com lista de IPs](https://broadrouter.com/pt/guides/api-keys-ip-allow-lists/) (guia)
-   [Agentes de longa duração: timeouts, retentativas e checkpoints](https://broadrouter.com/pt/blog/long-running-agents-timeouts-retries/) (artigo)
-   [Chave de API de LLM por hora: preço fixo por hora, explicado](https://broadrouter.com/pt/blog/hourly-llm-api-key-explained/) (artigo)

Teste com a sua carga de trabalho real. Contas novas começam com US$ 5 de crédito para Gemma e transcrição. DeepSeek, GLM e Qwen3.8 exigem uma recarga.

[Começar](https://inference.broadnet.ai/account/?utm_source=broadrouter&utm_medium=referral&utm_campaign=pt-glossary-idempotency-key&utm_content=page-cta) ·

**Fontes**

-   [IETF HTTPAPI, The Idempotency-Key HTTP Header Field (Internet-Draft)](https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/)
-   [AWS Builders' Library, timeouts, novas tentativas e backoff com jitter (idempotency tokens)](https://builder.aws.com/content/3EumjoZascWd1oZiEgL8ORlv3qE/timeouts-retries-and-backoff-with-jitter)
-   [Referência da API da BroadNet Inference, chaves por hora (idempotência com request\_id) (em inglês)](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=pt-glossary-idempotency-key&utm_content=sources#hourly-keys)
