Redes não são perfeitas. Quando uma requisição dá timeout, você não sabe se ela chegou até nós e já gerou custo. Com um Idempotency-Key, você pode repeti-la sem risco. Além disso, há cabeçalhos que informam quantas requisições você ainda pode enviar e quanto tempo deve esperar. Veja aqui como usar os dois para montar uma lógica de repetição robusta.
O que um Idempotency-Key faz
Em uma requisição de escrita (POST, PUT, PATCH, DELETE), você envia o cabeçalho Idempotency-Key com um valor gerado para essa operação específica. Se depois você enviar exatamente a mesma requisição com a mesma chave, não a executamos de novo. Se a primeira requisição tiver sido concluída com sucesso, você recebe a resposta armazenada, sem novo custo.
curl https://api.flowmodels.one/v1/chat/completions \
-H "Authorization: Bearer at_sua_chave" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: pedido-58213-resumo" \
-d '{"model": "groq/openai/gpt-oss-120b", "messages": [{"role": "user", "content": "Resuma o pedido 58213."}]}'
A chave tem de 1 a 128 caracteres e é composta de letras, dígitos, ponto, sublinhado e hífen. Um UUID sempre serve. Por padrão, guardamos a resposta armazenada por 24 horas.
Em uma resposta repetida, o cabeçalho traz Idempotent-Replay: true. O corpo traz o flowai_request_id da primeira requisição, e o cabeçalho x-request-id traz o identificador da repetição atual.
As três regras da chave
- Uma chave por operação, não por tentativa. Gere a chave antes do primeiro envio e use a mesma em todas as repetições dessa operação.
- Depois de uma interrupção, não troque de chave. A primeira requisição pode já ter sido processada e cobrada. Uma chave nova faria com que ela fosse executada uma segunda vez.
- Requisição alterada, chave nova. Se você enviar com a mesma chave um conteúdo ou um nome de arquivo diferente, a API responde com
422 idempotency_key_reuse.
Se a primeira requisição ainda estiver rodando, ou se o resultado dela não for conhecido com certeza depois de uma falha, você recebe imediatamente 409 idempotency_key_in_progress. Nesse caso, espere um pouco e repita com a mesma chave.
O Idempotency-Key só funciona em requisições JSON e multipart. Com outro Content-Type, você recebe 415 invalid_content_type.
Ler os cabeçalhos de rate limit
Toda resposta contabilizada no seu limite de requisições traz estes cabeçalhos:
x-ratelimit-limit-requests: quantas requisições por minuto você pode enviarx-ratelimit-remaining-requests: quantas ainda restamx-ratelimit-reset-requests: quando a cota volta a ficar cheia, por exemplo0sou1m30s
Em recusas por saldo, limite de gastos ou excesso de requisições simultâneas, esses cabeçalhos não aparecem, porque o motivo não é o limite por minuto. O funcionamento dos níveis está em Limite de requisições: como funcionam os níveis.
O que você pode repetir automaticamente
| Resposta | Repetir automaticamente? |
|---|---|
429 rate_limit_exceeded |
sim, depois do tempo de espera de Retry-After |
429 concurrent_requests_exceeded |
sim, depois de Retry-After, e enviando menos em paralelo |
502, 503 provider_overloaded, 503 routing_unavailable |
sim, depois de Retry-After ou com tempo de espera crescente |
409 idempotency_key_in_progress |
sim, espere um pouco e use a mesma chave |
429 insufficient_quota, 429 spend_limit_exceeded |
não, primeiro altere o saldo ou o limite |
400, 401, 403, 404, 422 |
não, primeiro corrija a requisição |
Requisições recusadas com 429 não custam nada e não deixam nenhum registro de idempotência armazenado.
Um exemplo em Python
import time, uuid, requests
URL = "https://api.flowmodels.one/v1/chat/completions"
REPETIVEIS = {"rate_limit_exceeded", "concurrent_requests_exceeded", "idempotency_key_in_progress"}
def codigo_de_erro(resposta):
try:
return (resposta.json().get("error") or {}).get("code")
except ValueError:
return None
def enviar_requisicao(payload):
chave = str(uuid.uuid4()) # uma vez por operação, igual em todas as tentativas
for tentativa in range(5):
try:
resposta = requests.post(
URL,
headers={"Authorization": "Bearer at_sua_chave", "Idempotency-Key": chave},
json=payload,
timeout=120,
)
except requests.exceptions.RequestException:
time.sleep(2 ** tentativa) # timeout: enviar de novo com a mesma chave
continue
if resposta.status_code < 400:
return resposta.json()
if resposta.status_code in (502, 503) or codigo_de_erro(resposta) in REPETIVEIS:
time.sleep(int(resposta.headers.get("Retry-After", 2 ** tentativa)))
continue
resposta.raise_for_status() # não repetir nenhum outro caso
raise RuntimeError("FlowModels inacessível após 5 tentativas")
Aqui, um timeout do seu lado é tratado como uma falha temporária: a requisição é enviada de novo com a mesma chave. Se a primeira já tiver dado certo, você recebe a resposta dela sem novo custo.
Bom saber
- Toda resposta traz o cabeçalho
x-request-id, inclusive as de erro. Grave esse valor nos seus logs, assim o suporte encontra uma requisição na hora. - Um stream interrompido não pode ser retomado. Para respostas longas, uma tarefa em segundo plano é mais robusta, veja Requisições longas em segundo plano.
- Todos os códigos de erro estão em Entender as mensagens de erro do FlowModels.