Erro 529 overloaded_error da Claude API — o que esse erro significa e como superá-lo

Impedir que novas tentativas ampliem a falha

Trate 529 como um "429 sem Retry-After": comece com espera progressiva exponencial de cerca de 2 segundos, adicione jitter, limite a 30〜60 segundos, desista após aproximadamente cinco tentativas e coloque o trabalho em uma fila. O que realmente funciona é o jitter: sem ele, todos os clientes voltam no mesmo instante e prolongam intacto o congestionamento do qual tentavam escapar.

Não caia; contorne

Defina antecipadamente uma cadeia de reserva para caminhos sensíveis à latência. Em endpoints compatíveis com a OpenAI, isso significa apenas mudar uma string — não é preciso conectar outro SDK nem abrir outra conta:

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

def complete(messages):
    last = None
    for model in PREFERRED:
        try:
            return client.chat.completions.create(
                model=model, messages=messages, max_tokens=800)
        except APIStatusError as e:
            if e.status_code not in (429, 500, 529):
                raise
            last = e          # 過載 —— 試下一個
    raise last

Só depois suspeite do seu próprio programa

Se apenas um tipo de solicitação retorna 529 enquanto outras chamadas no mesmo momento funcionam, não é uma falha geral: verifique se esse caminho está enviando prompts excepcionalmente grandes ou fazendo envios consecutivos em um loop muito curto. Por outro lado, se todas as chamadas começarem a retornar 529 ao mesmo tempo e depois se recuperarem sozinhas, a causa é capacidade — o que deve ser ajustado são as novas tentativas e a reserva, não uma refatoração.

529 é um problema meu?

Não. Este é um problema de capacidade no provedor. Sua responsabilidade é apenas dupla: não amplificar a falha (espera progressiva e jitter) e ter para onde desviar quando a falha ultrapassar seu orçamento de latência.

Qual é a diferença entre 529 e 429?

429 significa que você excedeu seu próprio limite e o servidor está saudável; 529 significa que o servidor está sobrecarregado e sua franquia está normal. Ambos podem ser repetidos, mas apenas 429 inclui uma indicação Retry-After.

Quanto tempo um 529 costuma durar?

Não é possível prever nem garantir — por isso a resposta correta é "espera progressiva limitada e fila", não definir um tempo de espera fixo no programa. Se o caminho tem um orçamento de latência, quem deve assumir é a reserva, não a espera.

Chamadas que falham com 529 são cobradas?

Pela Kunavo, não: solicitações encerradas com erro não entram na cobrança. Se você contratar diretamente com o provedor, depende das regras de cobrança de cada um.