Erro 529 overloaded_error na API da Claude — o que significa e como contornar

O 529 é o único erro da Claude que o seu código não causou: a própria Anthropic está sobrecarregada. Não dá para corrigir — dá para absorver bem. Isso significa retry paciente, um modelo de reserva e nunca amplificar o incidente com tentativas imediatas.

O erro

resposta (HTTP 529)

{
  "type": "error",
  "error": { "type": "overloaded_error",
             "message": "Overloaded" }
}

Causas e soluções em resumo

Causa	Solução
Saturação do provedor (dias de lançamento, incidentes regionais)	Backoff exponencial com jitter. Consulte a página de status do provedor em vez de refazer o deploy.
Seu pico de tráfego caiu durante um incidente parcial	Distribua os jobs em lote; dez minutos de espera costumam resolver.
Retry imediato em loop	Tentar de novo na hora multiplica a carga e prolonga o incidente para todo mundo, inclusive para você.

Faça retry como um bom cidadão

Trate o 529 como um 429 sem cabeçalho retry-after: backoff exponencial começando em ~2s, com jitter, teto de 30–60s, desistindo depois de ~5 tentativas e enfileirando o trabalho. O mesmo ramo de código que trata 429 serve para 529.

retry.py

import time, random
from openai import APIStatusError

def com_retry(fn, tentativas=5):
    for i in range(tentativas):
        try:
            return fn()
        except APIStatusError as e:
            if e.status_code not in (429, 500, 529):
                raise
            espera = min(2 ** i + random.random(), 60)
            time.sleep(espera)
    raise RuntimeError("esgotou as tentativas")

Troque de modelo em vez de cair

Em caminhos sensíveis a latência, defina uma reserva: dentro da mesma família (Sonnet → Haiku) o comportamento fica parecido; entre provedores (Claude → GPT) você sobrevive a um incidente inteiro. Em um endpoint compatível com OpenAI isso é a troca de uma string.

failover.py

PREFERIDOS = ["claude-sonnet-5", "claude-haiku-4-5", "gpt-5-6-terra"]

def completar(mensagens):
    ultimo = None
    for modelo in PREFERIDOS:
        try:
            return client.chat.completions.create(
                model=modelo, messages=mensagens, max_tokens=800)
        except APIStatusError as e:
            if e.status_code not in (429, 500, 529):
                raise
            ultimo = e          # saturado — tenta o próximo
    raise ultimo

Não confunda 529 com 429 nem com 402

429 quer dizer que você passou dos seus limites (o servidor está bem). 529 quer dizer que o servidor está sobrecarregado (sua cota está bem). 402 quer dizer saldo insuficiente. Os três se parecem no log e têm correções completamente diferentes: só o 429 e o 529 devem ser repetidos.

Se você estiver chamando pela Kunavo

Na Kunavo o mesmo catálogo multimodelo fica atrás de uma única chave e de uma única carteira, então o failover entre provedores do exemplo acima é a troca do nome do modelo — não exige segunda conta nem segundo cadastro. Requisições que falham não são cobradas. Capacidade e preço são perguntas separadas; para a segunda, as tarifas por token estão em nosso guia de preços da API da Claude.

Perguntas frequentes

O erro 529 é culpa minha?

Não. É capacidade do lado do provedor. Suas únicas responsabilidades são não amplificar o problema (backoff com jitter) e ter para onde migrar se o incidente durar mais que o seu orçamento de latência.

Qual a diferença entre 529 e 429?

429 significa que você ultrapassou seus limites; 529 significa que o servidor está sobrecarregado. Ambos podem ser repetidos, mas só o 429 costuma vir com uma dica de retry-after.

Vou ser cobrado por uma requisição que deu 529?

Não deveria — a requisição não produziu tokens. Na Kunavo, requisições com falha não são debitadas do saldo.

Guias relacionados

Mais detalhes sobre o significado dos erros estão em referência de erros; obter uma chave leva um minuto por meio de cadastro e da guia de autenticação.