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.

Resposta error.type retry-after O que significa O que fazer
529 overloaded_error Use-o se estiver lá A API está sobrecarregada para todos os utilizadores Aguarda um pouco e tenta novamente algumas vezes
429 rate_limit_error Yes A sua organização excedeu o número de pedidos, os tokens de entrada ou os output tokens por minuto, ou acelerou demasiado rápido e atingiu um limite de aceleração Espera o tempo que retry-after disser
429 rate_limit_error, com error.details.error_code definido para enforced_spend_limit_reached No A sua organização atingiu o limite mensal de despesa do seu escalão de utilização Não tente novamente. O uso fica em pausa até às 00:00 UTC do primeiro dia do mês seguinte, ou até passar para um nível superior.
400 invalid_request_error No A utilização atingiu um limite de despesa que definiu para a sua organização ou espaço de trabalho Aumentar ou remover o limite

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.

Approach O que encontra Do que sentes falta
Aguardar o ambiente de produção Sobrecargas reais Tudo, até que um utilizador o prima
Simula a API nos teus testes, ou deixa o teu agente de programação escrever o mock Se o seu ramo de erro é executado Os códigos de estado reais e corpos de erro do Anthropic, e a política de retentativas do teu SDK. A tua aplicação também precisa de um switch só de teste para chegar ao mock.
Chame a API real até falhar Comportamento real Não podes desencadear um 529 a pedido, nem podes desencadear com segurança um limite de despesa de todo
Interceta o tráfego real da tua aplicação e devolve respostas 529 e 429 a pedido URLs reais, o seu SDK real e política de retentativas, e o próprio formato de erro do Anthropic Nada na tua aplicação muda, por isso não testa o teu código isoladamente. Guarda os testes unitários para isso.

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"
Preset O que devolve
anthropic-throttling Ao acaso, 1 em cada 4 429 respostas rate_limit_error (pedidos, tokens de entrada, tokens de saída e limite de aceleração) ou uma resposta 529 overloaded_error. Nas respostas 429, o Dev Proxy define retry-after e avisa-te quando a tua app chama a API novamente demasiado cedo.
anthropic-random-errors Ao acaso, 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 pedidos

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

Testa a minha aplicação com erros aleatórios

Ver também

  • Última atualização a