Erro 429 na API de IA: backoff, fila e fallback

O erro 429 (Too Many Requests) é o jeito da API dizer que você passou do limite — não que ela quebrou. A reação errada (repetir a chamada na hora, várias vezes) transforma um soluço em uma queda: você empilha mais requisições sobre um endpoint que já pediu trégua. A reação certa é uma combinação de três coisas: respeitar o sinal, suavizar os picos e ter um plano B. Este guia mostra como tratar o erro 429 e o limite de requisições sem derrubar a automação.

O que o 429 realmente diz

As APIs de IA impõem dois limites simultâneos: RPM (requisições por minuto) e TPM (tokens por minuto). Você pode estourar o TPM mesmo com poucas requisições, se cada uma for enorme. Quando isso acontece, a resposta vem com status 429 e, quase sempre, um cabeçalho Retry-After dizendo em quantos segundos tentar de novo. Esse cabeçalho é ouro: ele tira você do chute.

Reaja certo: respeite o Retry-After

A primeira regra é nunca repetir imediatamente. Respeite o Retry-After quando houver e, na ausência dele, use recuo exponencial com jitter — o intervalo cresce a cada tentativa e ganha um ruído aleatório que evita que mil clientes voltem todos no mesmo instante (o efeito “manada”):

import time, random

def call_with_backoff(send, max_tries=5):
    for attempt in range(max_tries):
        resp = send()
        if resp.status_code != 429:
            return resp
        # respeita o servidor; senao, backoff exponencial + jitter
        retry_after = resp.headers.get("Retry-After")
        wait = float(retry_after) if retry_after else (2 ** attempt)
        wait += random.uniform(0, 0.5 * wait)   # jitter anti-manada
        time.sleep(wait)
    raise RuntimeError("limite persistente apos varias tentativas")

Repare no teto de tentativas: insistir para sempre só queima cota e, em APIs pagas, dinheiro. Depois de algumas tentativas, é hora do plano B.

Suavize os picos com uma fila

Backoff resolve a falha pontual; ele não resolve o padrão de mandar 300 requisições de uma vez. Para isso, coloque uma fila entre a sua aplicação e a API e processe em ritmo constante, abaixo do limite. No WordPress, o Action Scheduler faz isso sem você manter um worker próprio:

<?php
// Enfileira em vez de chamar a API na hora do pico.
foreach ($itens as $item) {
    as_enqueue_async_action('wpraiz_processa_ia', ['id' => $item->id], 'ia');
}

// Cada job processa 1 item, no ritmo do worker (abaixo do RPM).
add_action('wpraiz_processa_ia', function ($id) {
    $resp = call_with_backoff_php($id);   // sua chamada resiliente
    // ... persiste o resultado
});

A fila troca uma rajada que estoura o limite por um fluxo previsível que cabe nele. O usuário não espera a API porque o trabalho roda em segundo plano.

Tenha um plano B: fallback

Quando o backoff esgota, desviar para um modelo ou provedor alternativo mantém o produto de pé. Esse desvio é o mesmo mecanismo que economiza dinheiro quando bem orquestrado — ver como não depender de um único modelo. A regra: o fallback é um caminho de degradação graciosa, não o caminho padrão; logue toda vez que ele for acionado, porque 429 constante é sinal de que o seu limite precisa subir.

Meça sua taxa de 429

Você não controla o que não mede. Registre a proporção de respostas 429 sobre o total e os cabeçalhos de limite que a API devolve. Uma taxa que cresce é alerta antecipado: ou o tráfego subiu, ou alguma feature passou a mandar prompts muito maiores. Acoplar isso ao controle de custo de tokens fecha o ciclo — quase sempre, quem estoura o TPM também está gastando à toa.

429 não é 500: saiba distinguir

Vale separar três respostas que parecem a mesma coisa e pedem reações opostas. O 429 diz “você passou do seu limite” — a culpa é do seu ritmo, e backoff resolve. O 503 ou 529 diz “eu estou sobrecarregado” — a culpa é do lado de lá, e insistir não adianta nada; é hora de desviar. Já o 400 por excesso de tokens não é limite de taxa: é uma requisição grande demais, que vai falhar igual daqui a uma hora. Tratar os três com a mesma rotina de repetição é o erro mais comum, e o mais caro, porque só o primeiro melhora com espera.

Sua taxa de 429 é um termômetro do fornecedor

Há uma leitura do 429 que quase ninguém faz: ele é o sinal mais precoce de que a capacidade do seu fornecedor está apertando. Um aumento gradual, sem crescimento equivalente do seu tráfego, não é problema seu — é aperto do lado de lá, e ele chega bem antes de qualquer comunicado oficial.

Isso deixou de ser hipótese. Os próprios laboratórios de fronteira estão tratando restrição de fornecimento como risco de negócio, a ponto de montar times para desenhar o próprio silício. Se quem vende inferência se protege disso, quem compra deveria fazer o mesmo — e o painel de 429 é o instrumento mais barato para enxergar o aperto antes que ele vire indisponibilidade no seu produto.

Estratégias lado a lado

Checklist do 429

• Nunca repita imediatamente; respeite o Retry-After.
• Use backoff exponencial com jitter e um teto de tentativas.
• Enfileire o processamento em lote abaixo do RPM/TPM.
• Tenha fallback como degradação graciosa, com log a cada uso.
• Monitore a taxa de 429 como alerta antecipado — inclusive de aperto do fornecedor.
• Não trate 503/529 nem 400 por tamanho como se fossem 429: só o 429 melhora com espera.