Anthropic 529 overloaded_error: o que significa e como lidar com isso

A API da Claude devolve 529 com o tipo de erro overloaded_error quando a API está temporariamente sobrecarregada. Segundo a Anthropic, pode acontecer quando a API tem um tráfego elevado para todos os utilizadores. O seu pedido está bem. A API está ocupada, por isso recusou o pedido. Quando a sua organização ultrapassa os seus próprios limites de taxa, recebe um 429 em vez disso. O corpo da resposta tem a mesma forma que qualquer outro erro da API do Claude: um top-level type de error, um error objeto com type e message, e um request_id que podes fornecer ao suporte da Anthropic. Para mais informações, consulte Erros da API do Claude.

529, 429, ou limite de gasto: como distingui-los

A API Claude utiliza erros de aspeto semelhante para problemas muito diferentes. Alguns desaparecem se esperares. Um não vai embora até ao próximo mês.

Um spend-cap 429 tem o mesmo tipo de erro que um limite de taxa, por isso o código que tenta novamente a cada rate_limit_error continua a falhar. Anthropic nota que as tentativas falham até o acesso ser retomado, incluindo as tentativas automáticas do SDK. Para mais detalhes, veja Atingir o seu limite de despesa.

Como lidar com um plano 529

1. Verifique o código de estado antes de tentar novamente. Um 529 e um 429 precisam de diferentes tempos de espera, e um 429 sem retry-after não precisa de voltar a tentar.
2. Recua perante um 529. Tenta novamente com retardo exponencial e jitter aleatório, e pára depois de algumas tentativas. Se a resposta tiver um retry-after cabeçalho, espere esse tempo em vez disso.
3. Deixa o SDK fazer as primeiras novas tentativas. Os SDKs oficiais da Anthropic repetem automaticamente após erros de ligação, limites de taxa e erros 5xx duas vezes por defeito, com retrocesso exponencial, e respeitam retry-after quando este está presente. Podes alterar a contagem com max_retries (maxRetries no TypeScript). Quando o SDK esgota as tentativas de nova tentativa, o teu código recebe o erro.
4. Pare de tentar novamente devido a um limite de gastos. Se uma resposta 429 não tiver o cabeçalho retry-after, informa o utilizador e avisa-te.
5. Mantenha o utilizador informado. Coloque o trabalho em fila e tente novamente mais tarde, ou mostre uma mensagem clara de "ocupado, tente novamente dentro de um minuto" em vez de um erro genérico.

No SDK de Python, um 429 gera anthropic.RateLimitError e qualquer código de estado 500 ou superior, incluindo 529, gera anthropic.InternalServerError:

import anthropic

client = anthropic.Anthropic(max_retries=4)


def summarize(text: str) -> str | None:
    try:
        message = client.messages.create(
            model="claude-sonnet-5",
            max_tokens=1024,
            messages=[{"role": "user", "content": f"Summarize:\n\n{text}"}],
        )
    except anthropic.RateLimitError as e:
        if "retry-after" not in e.response.headers:
            # Spend cap: every retry fails until access resumes
            alert_admin(e)
            return None
        raise
    except anthropic.InternalServerError as e:
        if e.status_code == 529:
            # Overloaded after all SDK retries: queue the job for later
            queue_for_later(text)
            return None
        raise
    return next(block.text for block in message.content if block.type == "text")

Como testar se a sua aplicação lida com um 529

Raramente se vê um 529 enquanto desenvolve. Depende do tráfego de cada utilizador da API Claude, por isso não podes desencadeá-lo. A forma como testas decide se encontras os bugs antes dos teus utilizadores.

Experimente na sua app

O Proxy de desenvolvimento interceta os pedidos da sua aplicação para https://api.anthropic.com e devolve erros no formato de erro do Anthropic, enquanto a sua aplicação continua a chamar o URL real. Descarrega uma predefinição e começa o Dev Proxy com ela:

devproxy config get anthropic-throttling
devproxy --config-file "~dataFolder/configs/anthropic-throttling/.devproxy/devproxyrc.json"

Nenhuma das predefinições inclui um limite de despesas 429. Para testar esse caminho, adicione uma resposta sem cabeçalho retry-after ao ficheiro do anthropic-errors.json preset:

{
  "statusCode": 429,
  "headers": [
    { "name": "content-type", "value": "application/json" }
  ],
  "body": {
    "type": "error",
    "error": {
      "type": "rate_limit_error",
      "message": "You have reached your API usage limits.",
      "details": { "error_code": "enforced_spend_limit_reached" }
    }
  }
}

Para que todos os pedidos falhem, para que vejas o que acontece quando o SDK esgotar as tentativas de repetição, inicia o Dev Proxy com --failure-rate 100. Para mais informações, consulte taxa de falha no pedido de alteração. Para instalar Dev Proxy, consulte Configurar Dev Proxy.

Passos seguintes

Ver também

• 429 Demasiados pedidos: o que significa e como lidar com isso
• Erros 500, 502, 503 e 504 das APIs: o que significam e como lidar com eles
• O que é o throttling?
• Teste que a minha aplicação lida com o controle de fluxo corretamente