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

A API do Claude retorna 529 com o tipo overloaded_error de erro quando a API é temporariamente sobrecarregada. De acordo com Anthropic, isso pode acontecer quando a API experimenta tráfego alto entre todos os usuários. Sua solicitação está boa. A API está ocupada, portanto, ela recusou a solicitação. Quando sua organização ultrapassa seus próprios limites de taxa, você obtém um 429. O corpo da resposta tem a mesma forma que todos os outros erros da API Claude: um type de nível superior de error, um objeto error com type e message, e um request_id que você pode fornecer ao suporte da Anthropic. Para obter mais informações, consulte os erros da API de Claude.

529, 429, ou limite de gastos: como diferenciá-los

A API Claude usa erros parecidos para problemas muito diferentes. Alguns vão embora se você esperar. Isso não vai embora até o mês que vem.

Resposta error.type retry-after O que significa O que fazer
529 overloaded_error Use isso se ele estiver lá A API está sobrecarregada para todos os usuários Aguardar um pouco e tentar novamente algumas vezes
429 rate_limit_error Yes Sua organização excedeu o limite de solicitações, tokens de entrada ou tokens de saída por minuto, ou aumentou muito rápido e atingiu um limite de aceleração Aguarde o tempo indicado por retry-after
429 rate_limit_error, com error.details.error_code definido como enforced_spend_limit_reached No Sua organização atingiu o limite mensal de gastos do nível de uso Não tente novamente. O uso fica pausado até 00:00 UTC no primeiro dia do mês seguinte ou até que você mude para um nível superior.
400 invalid_request_error No O uso atingiu um limite de gastos que você definiu em sua organização ou workspace Aumentar ou remover o limite

Um limite de gastos 429 tem o mesmo tipo de erro que um limite de taxa, de modo que o código que tenta novamente a cada rate_limit_error continua falhando. Anthropic observa que as tentativas falharão até que o acesso seja retomado, incluindo as tentativas automáticas do SDK. Para obter detalhes, consulte Atingindo o limite de gastos.

Como lidar com um plano 529

  1. Verifique o código de status antes de tentar novamente. Uma 529 e uma 429 precisam de tempos de espera diferentes, e um 429 sem retry-after não precisa de nova tentativa.
  2. Reduzir contribuições para um plano 529. Tente novamente com recuo exponencial e jitter aleatório e pare após algumas tentativas. Se a resposta tiver um cabeçalho retry-after, aguarde esse tempo.
  3. Deixe o SDK fazer as primeiras novas tentativas. Os SDKs oficiais da Anthropic repetem erros de conexão, limites de taxa e erros 5xx duas vezes por padrão, com backoff exponencial, e respeitam retry-after quando estiver presente. Você pode alterar a contagem com max_retries (maxRetries em TypeScript). Quando o SDK fica sem tentativas, o código recebe o erro.
  4. Pare de tentar novamente ao atingir um limite de gastos. Se um 429 não tiver cabeçalho retry-after, informe o usuário e gere um alerta para si mesmo.
  5. Mantenha o usuário informado. Enfileira o trabalho e tente novamente mais tarde ou mostre uma mensagem clara "ocupado, tente novamente em um minuto" em vez de um erro genérico.

No SDK do Python, um aumento de 429 anthropic.RateLimitError e qualquer status igual a 500 ou superior, incluindo 529, geraanthropic.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 seu aplicativo manipula um 529

Você raramente vê um 529 durante o desenvolvimento. Depende do tráfego de todos os usuários da API claude, para que você não possa acioná-lo. A maneira como você testa determina se você encontra os bugs antes que seus usuários o façam.

Approach O que você encontra Do que você sente falta
Aguardar a produção Sobrecargas reais Tudo, até que um usuário toque nele
Simular a API em seus testes ou deixar seu agente de codificação escrever a simulação Se o branch de erro for executado Os códigos de status reais e os corpos de erro da Anthropic, e a política de repetição do seu SDK. Seu aplicativo também precisa de uma opção somente de teste para acessar o mock.
Chame a API real até que ela falhe Comportamento real Você não pode acionar um erro 529 sob demanda e não pode aplicar com segurança um limite de gastos
Interceptar o tráfego real do aplicativo e retornar 529s e 429s sob demanda URLs reais, seu SDK real e política de repetição e o formato de erro do próprio Anthropic Nada muda no seu aplicativo, portanto, ele não testa seu código isoladamente. Guarde seus testes unitários para isso.

Experimente em seu aplicativo

Dev Proxy intercepta as solicitações do seu aplicativo para https://api.anthropic.com e retorna erros no formato de erro da Anthropic, enquanto seu aplicativo continua chamando a URL real. Baixe uma predefinição e inicie o Dev Proxy com ele:

devproxy config get anthropic-throttling
devproxy --config-file "~dataFolder/configs/anthropic-throttling/.devproxy/devproxyrc.json"
Preset O que ele retorna
anthropic-throttling A cada 4.429 respostas, 1 429 rate_limit_error (solicitações, tokens de entrada, tokens de saída e limite de aceleração) ou um 529 overloaded_error. Nos 429, o Proxy de Desenvolvimento define retry-after e informa quando seu aplicativo chama a API novamente muito cedo.
anthropic-random-errors Aleatoriamente, um dos erros da lista de erros da API claude, incluindo 400, 401, 402, 403, 404, 409, 413, 429, 500, 504 e 529, para 50% de solicitações

Nenhuma predefinição inclui um limite de gastos 429. Para testar esse caminho, adicione uma resposta sem cabeçalho retry-after ao arquivo da predefinição anthropic-errors.json:

{
  "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 fazer com que todas as solicitações falhem, para que você veja o que acontece quando o SDK fica sem tentativas de repetição, inicie o Dev Proxy com --failure-rate 100. Para obter mais informações, consulte Taxa de falha da solicitação de alteração. Para instalar o Dev Proxy, consulte Configurar o Dev Proxy.

Próximas Etapas 

Teste meu aplicativo com erros aleatórios

Consulte também

  • Última atualização em