Anthropic 529 overloaded_error: qué significa y cómo controlarlo

La API de Claude devuelve 529 con el tipo de error overloaded_error cuando la API está temporalmente sobrecargada. Según Anthropic, esto puede ocurrir cuando la API registra un tráfico elevado por parte de todos los usuarios. Su solicitud está bien. La API está ocupada, por lo que rechazó la solicitud. Cuando su organización supere sus propios límites de tasa, obtendrá un valor de 429 en su lugar. El cuerpo de la respuesta tiene la misma estructura que cualquier otro error de la API de Claude: un type de nivel superior de tipo error, un objeto error con type y message, y un request_id que puedes facilitar al servicio de asistencia de Anthropic. Para obtener más información, consulte Errores de la API de Claude.

529, 429 o límite de gasto: cómo distinguirlos

La API de Claude utiliza errores de aspecto similar para problemas muy diferentes. Algunos desaparecen si esperas. Uno de ellos no desaparecerá hasta el mes que viene.

Un error 429 de límite de gasto tiene el mismo tipo de error que un límite de tasa, por lo que el código que reintenta cada rate_limit_error seguirá fallando. Anthropic señala que los reintentos fallan hasta que se reanuda el acceso, incluidos los reintentos automáticos del SDK. Para más detalles, consulta Alcanzar tu límite de gasto.

Cómo gestionar un 529

1. Compruebe el código de estado antes de volver a intentarlo. Un 529 y un 429 requieren tiempos de espera diferentes, y un 429 sin retry-after no necesita ningún reintento.
2. Aplaza el intento en caso de un 529. Vuelve a intentarlo con retroceso exponencial y fluctuación aleatoria, y detén el proceso tras unos cuantos intentos. Si la respuesta incluye un encabezado retry-after, espera ese tiempo en su lugar.
3. Deje que el SDK realice los primeros reintentos. Los SDK oficiales Anthropic reintentan los errores de conexión, los límites de tasa y los errores 5xx dos veces de forma predeterminada, con retroceso exponencial y respetan retry-after cuando está presente. Puede cambiar el recuento con max_retries (maxRetries en TypeScript). Cuando el SDK se queda sin reintentos, tu código recibe el error.
4. Deja de reintentar cuando se alcance el límite de gasto. Si un código 429 no incluye el encabezado retry-after, avisa al usuario y activa una alerta para ti mismo.
5. Mantenga informado al usuario. Poner en cola el trabajo e intentarlo más tarde o mostrar un mensaje "ocupado, inténtelo de nuevo en un minuto" en lugar de un error genérico.

En el SDK de Python, un 429 genera anthropic.RateLimitError y cualquier estado de 500 o superior, incluido 529, genera 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")

Cómo comprobar que tu aplicación administra un código 529

Rara vez ves un 529 mientras desarrollas. Depende del tráfico de todos los usuarios de Claude API, por lo que no se puede desencadenar. La forma en que realices las pruebas determina si detectas los errores antes que tus usuarios.

Pruébalo en tu app

Dev Proxy intercepta las solicitudes de tu aplicación a https://api.anthropic.com y devuelve errores en el formato de error de Anthropic, mientras tu aplicación sigue llamando a la URL real. Descargue un ajuste preestablecido e inicie Dev Proxy con él:

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

Ninguno de los valores preestablecidos incluye un límite de gasto 429. Para probar esa ruta, añade una respuesta sin un encabezado retry-after al archivo anthropic-errors.json del preajuste:

{
  "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 todas las solicitudes fallen, de modo que puedas ver qué ocurre cuando el SDK agota los reintentos, inicia Dev Proxy con --failure-rate 100. Para obtener más información, consulte Tasa de fallos de las solicitudes de cambio. Para instalar Dev Proxy, consulte Configurar Dev Proxy.

Pasos siguientes

Consulte también

• 429 Demasiadas solicitudes: lo que significa y cómo controlarlo
• 500, 502, 503 y 504 errores de las API: qué significan y cómo controlarlos
• ¿Qué es la limitación de velocidad?
• Prueba de que mi aplicación controla la limitación correctamente