MandAPI
EntrarCriar conta

Erro 429: como diagnosticar rate limit sem piorar a fila

Resposta rápida

Um 429 significa que a requisição não foi aceita porque um limite de requisições, tokens ou cota foi atingido. Ele não prova que a chave é inválida, que o modelo não existe ou que o servidor caiu. Leia primeiro a mensagem do erro, o cabeçalho Retry-After — quando existir — e o identificador da requisição.

Em um gateway, o 429 pode nascer em dois pontos: no próprio gateway ou no provedor upstream. Por isso, o diagnóstico correto precisa registrar onde a chamada parou antes de aumentar concorrência ou repetir a requisição em loop.

O que o corpo e os headers entregam

Procure estes sinais na resposta:

  • HTTP 429 — a requisição foi rejeitada antes de produzir a resposta normal.
  • Retry-After — quando presente, indica uma espera mínima antes de tentar novamente.
  • Mensagem do erro — pode citar requisições por minuto, tokens por minuto, cadência da conta ou outra restrição.
  • x-request-id ou equivalente — permite correlacionar o incidente com o log do gateway.
  • Modelo e endpoint usados — um mesmo cliente pode passar em um modelo e falhar em outro com limite mais restrito.

Não existe um único “limite da MandAPI” que possa ser copiado de um artigo e aplicado a toda conta. Limites podem variar por chave, modelo, provedor, plano e janela de tempo. A resposta atual é a fonte mais confiável para o comportamento observado.

Fluxo de diagnóstico em cinco minutos

  1. Reproduza com uma única requisição. Isso separa um problema de rajada de um problema de conta.
  2. Guarde status, headers, corpo, modelo, horário UTC e request ID.
  3. Compare a concorrência atual com a taxa que funcionava antes.
  4. Verifique se o volume de tokens de entrada ou saída cresceu, mesmo sem aumentar o número de chamadas.
  5. Faça retry apenas após uma espera calculada. Não coloque todos os workers para tentar ao mesmo tempo.

Se o erro aparecer apenas em produção, execute o mesmo teste com o mesmo modelo e a mesma rota. Diferenças de proxy, timeout e pool de conexões também mudam a cadência vista pelo gateway.

Exemplo de retry responsável

O exemplo abaixo respeita Retry-After, adiciona jitter e limita o número de tentativas. Ele é um ponto de partida, não uma política universal de produção.

import os
import random
import time
import requests

API_KEY = os.environ["MANDAPI_API_KEY"]
URL = "https://api.mandapi.com/v1/chat/completions"
MODEL = os.environ["MANDAPI_MODEL"]

payload = {
    "model": MODEL,
    "messages": [{"role": "user", "content": "Responda apenas: ok"}],
}

for attempt in range(5):
    response = requests.post(
        URL,
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json=payload,
        timeout=30,
    )

    if response.status_code != 429:
        response.raise_for_status()
        break

    retry_after = response.headers.get("retry-after")
    if retry_after and retry_after.isdigit():
        wait_seconds = float(retry_after)
    else:
        wait_seconds = min(30.0, (2 ** attempt) + random.uniform(0, 1))

    print(
        "429; tentativa", attempt + 1,
        "aguardando", round(wait_seconds, 2),
        "request_id", response.headers.get("x-request-id", ""),
    )
    time.sleep(wait_seconds)
else:
    raise RuntimeError("Limite persistente após cinco tentativas")

O que não fazer

  • Repetir imediatamente em um while true: isso aumenta a rajada e pode prolongar o bloqueio.
  • Abrir mais conexões para “vencer” o limite: concorrência maior costuma piorar o 429.
  • Tratar 429 como 401: credencial inválida exige correção de chave; rate limit exige cadência ou cota.
  • Ignorar o request ID ao abrir suporte: sem ele, o diagnóstico fica genérico.
  • Assumir que todo 429 é cobrança: cota e rate limit são verificações relacionadas, mas não idênticas.

Como confirmar que a correção funcionou

Uma correção saudável deve produzir três evidências:

  1. O mesmo teste passa com uma única requisição.
  2. A produção não gera novas rajadas quando o retry é acionado.
  3. O log mostra redução de 429 sem aumento de timeout ou erro 5xx.

Se o volume continuar alto, reduza a concorrência, distribua o tráfego ao longo da janela e revise o consumo de tokens. Em fluxos com muitas chamadas curtas, limitar concorrência costuma ser mais eficaz do que apenas aumentar o intervalo entre tentativas.

Próximos passos

  • Revise os códigos e o envelope de erro em Erros da API.
  • Confirme a chave e o formato Bearer em Como usar sua API Key.
  • Veja o caminho completo de cadastro, chave e primeira chamada em Início rápido.
  • Consulte Preços quando a origem do erro envolver volume de uso ou necessidade de aumento de capacidade.

Fontes

Última verificação editorial: 20 de setembro de 2026. Os limites efetivos podem mudar; confirme a resposta atual da API e o painel da sua conta.