FlowModels

Repetir requisições com segurança: Idempotency-Key, Retry-After e cabeçalhos de rate limit

Publicado em 11. novembro 2026

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

  1. 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.
  2. 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.
  3. 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 enviar
  • x-ratelimit-remaining-requests: quantas ainda restam
  • x-ratelimit-reset-requests: quando a cota volta a ficar cheia, por exemplo 0s ou 1m30s

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

Este artigo foi útil?

Voltar para Modelos, limites e erros