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:
- Seu servidor envia
POST /agents/v1/calls. - A Qomni cria a chamada e o agente liga para o cliente.
- A resposta se perde no caminho (a conexão cai, seu tempo de espera se esgota).
- Seu código vê um erro de rede e tenta de novo.
- 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.
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" }'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,
)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.
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
GETjá 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: o que significa cada código antes de decidir tentar de novo.
- Limites de uso: o
Retry-Afterde um429. - O edge e as células: de onde sai um
origin_unavailable.