BroadRouter

Erro 429 em API de LLM: backoff, jitter e limitadores

Pela equipe da BroadNet Inference · 5 min de leitura · Publicado em · Atualizado em

Um 429 significa que você bateu num limite de taxa, de concorrência ou de gasto. Tente de novo com backoff exponencial limitado e jitter aleatório, respeitando o Retry-After quando ele vier. Depois evite a maioria dos 429: limite as requisições em andamento com um semáforo no limite da chave e coloque o resto numa fila. Repita os 5xx do mesmo jeito; os outros 4xx devem ser corrigidos.

Um 429 significa que o seu tráfego passou de um rate limit: requisições por minuto, requisições em andamento, tokens por minuto ou gasto. A correção tem duas metades. Tentar de novo direito: backoff exponencial limitado com jitter aleatório, respeitando o Retry-After. Enviar menos de uma vez: um semáforo no limite de requisições em andamento da chave, mais uma fila. As duas estão abaixo, com código.

Para a referência completa de códigos de status, veja o guia de erros e novas tentativas; para execuções de agentes que duram horas, com checkpoints e timeouts, veja agentes de longa duração: timeouts e novas tentativas.

Qual é a diferença entre 429 e 5xx?

Status De quem é o problema Tentar de novo? Como
429 O seu tráfego passou de um limite Sim Backoff com jitter; respeite o Retry-After; reduza a concorrência
500 / 502 / 503 / 504 Lado do servidor Sim Backoff exponencial limitado
Conexão encerrada, timeout Rede ou servidor Normalmente Backoff; em streams, só se uma nova cobrança for aceitável
400 / 422 Requisição inválida Não Corrija o payload
401 / 402 / 403 Chave, saldo ou política Não Corrija a chave, recarregue a conta, corrija a lista de IPs permitidos
413 Requisição grande demais Não Reduza o tamanho

Na BroadNet Inference, um 429 pode indicar qualquer um de quatro limites: taxa, concorrência, tokens por minuto ou gasto. Um limite de gasto não se resolve em 30 segundos. A documentação da BroadNet não diz qual campo do corpo do erro identifica o limite, então registre o corpo e compare com os limites mostrados nos detalhes da sua chave.

O nosso conjunto de dados aberto de planos gratuitos e rate limits de APIs de LLM compara o que 14 provedores publicam sobre acesso gratuito, rate limits iniciais, exigência de cartão e treinamento com dados do plano gratuito, com fonte e data de cada valor.

Quais limites causam 429?

Conheça os números com que você está trabalhando. Na BroadNet Inference:

Tipo de chave Requisições / minuto Em andamento Outros
Pagamento por uso 30 4 Orçamento de gasto compartilhado
Chave por hora 120 1 stream 300,000 tokens / minuto
Sessão de plano ilimitado — 1 requisição por sessão Sem medidor de tokens

Em LLMs, o que mais pesa é o número de requisições em andamento. Uma resposta em streaming ocupa a sua vaga até chegar o último token, então uma resposta longa a mantém ocupada por todo o tempo que o modelo leva para escrevê-la (a BroadNet informa uma velocidade típica de cerca de 100 tokens por segundo). Se você enviar mais chamadas em paralelo do que as 4 vagas da chave, as excedentes recebem 429, mesmo que você tenha enviado só um punhado de requisições naquele minuto. É um problema de concorrência, e só o backoff lida mal com ele. Para dimensionar workers em relação a um limite antes do lançamento, use a calculadora de rate limit de LLM gratuita. Para um job fixo com muitos itens, o planejador de jobs em lote de LLM transforma os mesmos limites num tempo de execução. Outros provedores contam de outro jeito (tokens por minuto, requisições por dia ou requisições em andamento); rate limits de APIs de LLM por provedor compara 13 deles a partir da própria documentação.

Como escrever backoff com jitter?

O backoff exponencial simples espera 1, 2, 4, 8 segundos. Se cem workers foram limitados no mesmo momento, todos voltam no mesmo momento. Na simulação da AWS com 100 clientes disputando o mesmo recurso, o full jitter reduziu o número de chamadas a menos da metade e terminou antes do backoff sem jitter. A versão mais simples, o full jitter, espera um tempo aleatório entre zero e o teto exponencial:

import os, random, time
from openai import OpenAI, RateLimitError, APIStatusError, APIConnectionError

client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"], max_retries=0)

RETRYABLE = {429, 500, 502, 503, 504}

def call_with_backoff(max_attempts=6, base=1.0, cap=60.0, **kwargs):
    for attempt in range(max_attempts):
        try:
            return client.chat.completions.create(**kwargs)
        except (RateLimitError, APIStatusError, APIConnectionError) as e:
            status = getattr(e, "status_code", None)
            if status is not None and status not in RETRYABLE:
                raise  # 400, 401, 403...: retrying will not help
            if attempt == max_attempts - 1:
                raise
            retry_after = None
            if getattr(e, "response", None) is not None:
                retry_after = e.response.headers.get("retry-after")
            wait = random.uniform(0, min(cap, base * 2 ** attempt))
            if retry_after and retry_after.isdigit():
                wait = max(wait, float(retry_after))
            time.sleep(wait)

max_retries=0 desliga as novas tentativas do próprio SDK, para você não repetir duas vezes. Se o comportamento embutido do SDK já atende, o contrário também funciona: dispense o seu loop e defina max_retries=4 no cliente, como mostra o guia do SDK Python. Os SDKs oficiais de Python e Node repetem por padrão erros de conexão, 408, 409, 429 e 5xx duas vezes.

Retry-After é um cabeçalho padrão (RFC 9110) que pode conter segundos ou uma data. A documentação da BroadNet não garante esse cabeçalho, então o código o trata como opcional.

Como evitar os 429 antes que aconteçam?

Limite as requisições em andamento ao limite da chave. Em Python, um asyncio.Semaphore resolve com um objeto e um bloco async with. O código usa 4 como exemplo; ajuste para o limite de requisições em andamento da sua chave (4 numa chave de pagamento por uso da BroadNet):

import asyncio, os
from openai import AsyncOpenAI

client = AsyncOpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"], max_retries=4)
slots = asyncio.Semaphore(4)  # match the key's in-flight limit

async def ask(prompt):
    async with slots:
        r = await client.chat.completions.create(
            model="broadnet/gemma-4-26b-a4b",
            messages=[{"role": "user", "content": prompt}],
        )
        return r.choices[0].message.content

async def main(prompts):
    return await asyncio.gather(*(ask(p) for p in prompts))

results = asyncio.run(main(["Summarise A", "Summarise B", "Summarise C"]))

O gather inicia todas as tarefas, mas só rodam ao mesmo tempo quantas o semáforo permitir. As outras esperam na fila do semáforo. Em Node, o pacote p-limit faz o mesmo, de novo com 4 como valor de exemplo:

// ES module (top-level await). npm install openai p-limit
import OpenAI from "openai";
import pLimit from "p-limit";

const client = new OpenAI({ baseURL: "https://inference.broadnet.ai/v1", apiKey: process.env.BROADNET_API_KEY, maxRetries: 4 });
const limit = pLimit(4); // match the key's in-flight limit

async function ask(prompt) {
  const r = await client.chat.completions.create({
    model: "broadnet/gemma-4-26b-a4b",
    messages: [{ role: "user", content: prompt }],
  });
  return r.choices[0].message.content;
}

const prompts = ["Summarise A", "Summarise B", "Summarise C"];
const results = await Promise.all(prompts.map((p) => limit(() => ask(p))));

Se você também precisa de um teto por minuto, adicione um token bucket que libera uma permissão a cada 60 / rpm segundos, onde rpm é o limite de requisições por minuto da sua chave (30 numa chave de pagamento por uso da BroadNet).

Quando você precisa de uma fila de verdade?

Um semáforo vive dentro de um processo. Quando vários workers ou servidores dividem uma chave, o limite é compartilhado e cada processo só enxerga o próprio tráfego. Aí:

  1. Coloque os jobs numa fila compartilhada (Redis, SQS, uma tabela do banco de dados).
  2. Rode um número fixo de consumidores, igual ao limite de requisições em andamento da chave.
  3. Dê um ID a cada job e guarde os resultados por ID, para que um job repetido não rode duas vezes.
  4. Mande o tráfego interativo e o tráfego em lote por chaves ou filas separadas, para que um acúmulo de lote nunca trave um usuário esperando resposta.

Para um job grande, de milhares de itens, sem Batch API, veja o executor em lote retomável.

Quais erros de nova tentativa transformam 429 em indisponibilidade?

  • Novas tentativas sem limite. Um loop de novas tentativas sem teto durante uma indisponibilidade longa multiplica a sua carga e, na cobrança por token, a sua conta.
  • Repetir às cegas um stream pela metade. Se o stream já devolveu tokens, uma nova tentativa é uma inferência nova, e o usuário pode ver o texto duas vezes. Veja o post sobre streaming para detectar streams incompletos.
  • Repetir erros de conta. Um 401 por franquia de pagamento por uso esgotada ou um 402 por saldo insuficiente não se resolvem sozinhos.

Registre cada nova tentativa com o status, o tempo de espera e o cabeçalho de resposta X-Request-ID, que a documentação da BroadNet pede para você guardar para o suporte. Uma taxa crescente de novas tentativas é o primeiro sinal de que você precisa de mais capacidade; o registro de uso mostra como registrar isso.

Onde a BroadNet Inference se encaixa

Os limites da BroadNet são publicados e pequenos o bastante para você projetar em torno deles: 4 requisições em andamento numa chave de pagamento por uso. Isso serve para apps e agentes, e é apertado demais para um job em lote que quer centenas de chamadas em paralelo numa só chave. Para agentes, um plano ilimitado não tem medidor de tokens e roda uma requisição por vez por sessão; para trabalho em paralelo você adiciona sessões, como descrito em rodar agentes de código em paralelo. Os limites atuais estão na referência da API.

Perguntas frequentes

O que significa o erro HTTP 429 numa API de LLM?

Too Many Requests. Você passou de um limite de requisições por minuto, de requisições em andamento, de tokens por minuto ou de gasto. A requisição não foi processada, então é seguro enviá-la de novo depois de esperar.

Quanto tempo devo esperar antes de tentar de novo depois de um 429?

Use o Retry-After se o servidor enviar. Caso contrário, comece com cerca de um segundo, dobre a cada tentativa, limite em algo entre 30 e 60 segundos e escolha uma espera aleatória entre zero e esse teto. Pare depois de quatro a seis tentativas.

Devo tentar de novo erros 500 e 503 de uma API de LLM?

Sim, com o mesmo backoff limitado. São erros do lado do servidor. Um 400, 401, 403 ou 422 vai falhar do mesmo jeito toda vez, então corrija a causa.

O SDK da OpenAI repete 429 automaticamente?

Sim. Os SDKs oficiais de Python e Node repetem por padrão erros de conexão, 408, 409, 429 e 5xx duas vezes, com um backoff exponencial curto. Aumente max_retries para jobs em lote e adicione o seu próprio limite de concorrência.

Por que recebo 429 se estou abaixo do limite de requisições por minuto?

Normalmente é o limite de concorrência. Respostas longas em streaming ficam em andamento por muitos segundos, então algumas chamadas em paralelo podem bater no teto de requisições em andamento enquanto a contagem por minuto parece baixa.

Ler em MarkdownPerguntar ao ChatGPTPerguntar ao ClaudePerguntar ao Perplexity