---
title: "Idempotência e novas tentativas"
description: "O que é uma requisição idempotente, quando é seguro repetir uma chamada à Qomni e como usar o header Idempotency-Key."
version: "pt-br"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.qomni.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Idempotência e novas tentativas

Uma requisição é **idempotente** quando repeti-la produz o mesmo resultado
que fazê-la uma única vez. Listar suas chamadas é idempotente: você faz isso dez
vezes e a lista não muda. Criar uma chamada não é: você a cria duas vezes e
o agente liga duas vezes para o mesmo cliente.

Redes falham, então seu código precisa tentar de novo. O problema é
repetir uma requisição que cria algo sem criá-lo duas vezes.

## Por que o problema existe

O caso perigoso não é quando a requisição falha. É quando você não sabe se falhou:

```mermaid
sequenceDiagram
  participant S as Seu servidor
  participant Q as Agents API
  S->>Q: POST /agents/v1/calls
  Q->>Q: cria call_01… e o agente liga
  Q--xS: a resposta se perde
  S->>Q: nova tentativa: POST /agents/v1/calls
  Q->>Q: cria call_02… e o agente liga de novo
  Q-->>S: 201 call_02…
```

1. Seu servidor envia `POST /agents/v1/calls`.
2. A Qomni cria a chamada e o agente liga para o cliente.
3. A resposta se perde no caminho (a conexão cai, seu tempo de espera
   se esgota).
4. Seu código vê um erro de rede e tenta de novo.
5. A Qomni cria uma segunda chamada e o cliente recebe duas.

Do seu lado, os passos 2 e 3 são invisíveis: uma falha de rede antes da
resposta parece igual a uma falha de rede antes de a requisição chegar.
Nenhum cliente consegue distingui-las sozinho.

## Como se resolve

A solução é você dar um nome a cada operação. Você envia um header
`Idempotency-Key` com um valor que escolhe, e repete esse mesmo valor em cada
nova tentativa da mesma operação. Assim a API reconhece a repetição e
devolve o resultado da primeira vez em vez de criar outra chamada.

```bash
curl https://api.qomni.ai/agents/v1/calls \
  -H "Authorization: Bearer $QOMNI_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-reminder" \
  -d '{ "to": "+15005550001" }'
```

```python
import os

import requests

key = os.environ["QOMNI_KEY"]
response = requests.post(
    "https://api.qomni.ai/agents/v1/calls",
    headers={
        "Authorization": f"Bearer {key}",
        "Idempotency-Key": "order-1042-reminder",
    },
    json={"to": "+15005550001"},
    timeout=10,
)
```

```typescript
const response = await fetch("https://api.qomni.ai/agents/v1/calls", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.QOMNI_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "order-1042-reminder",
  },
  body: JSON.stringify({ to: "+15005550001" }),
});
```

A chave boa sai dos seus próprios dados: o id do pedido a lembrar,
o id da consulta a confirmar, o id do cliente mais a data. Uma chave
aleatória gerada em cada tentativa não serve, porque cada tentativa levaria
uma chave nova.

> **Estado atual**
>
> A API aceita o header `Idempotency-Key` conforme o contrato, mas a
> deduplicação ainda não está ativa: hoje uma nova tentativa cria um segundo
> recurso. Enquanto isso, tente de novo só quando souber que a requisição não
> chegou (`503 origin_unavailable`, ou um erro de conexão antes de enviar o
> corpo) e guarde o `id` de cada resposta para não repetir uma operação que
> já tem resultado.

## Quando tentar de novo

| O que você recebeu | Tente de novo | Por quê |
|---|---|---|
| `503 origin_unavailable` | Sim, com backoff | A célula não recebeu a requisição. Nada foi feito. |
| `429 rate_limited` | Sim, após `Retry-After` segundos | A requisição não foi processada. |
| Erro de conexão antes de enviar o corpo | Sim | A requisição não chegou. |
| Tempo de espera esgotado aguardando a resposta | Só com `Idempotency-Key` | Pode ter chegado e ter sido processada. |
| `4xx` diferente de `429` | Não | A requisição está errada. Repeti-la igual vai falhar igual. |

Use um **backoff exponencial**: espere 1 segundo, depois 2, depois 4, com um
máximo de cinco tentativas. Tentar de novo sem esperar só piora uma célula que já
está saturada.

## Limites

- As requisições `GET` já são idempotentes. Não precisam do header.
- A chave identifica uma operação, não um recurso. Dois pedidos diferentes
  levam duas chaves diferentes mesmo que liguem para o mesmo número.
- A chave não muda o que a requisição faz. Se você tentar de novo com a mesma
  chave e outro corpo, o corpo que vale é o da primeira vez.

## Veja também

- [Erros](/pt-br/concepts/errors/): o que significa cada código antes de decidir tentar de novo.
- [Limites de uso](/pt-br/concepts/rate-limits/): o `Retry-After` de um `429`.
- [O edge e as células](/pt-br/concepts/edge/): de onde sai um `origin_unavailable`.

Source: https://docs.qomni.ai/pt-br/concepts/idempotency/index.mdx
