Los errores de la API de Claude se dividen, a grandes rasgos, en tres grupos: credenciales y formato de la petición, límites de tasa y capacidad, y longitud del contexto. El orden de resolución debería ser: primero el código de estado HTTP y el tipo de error, después el ID de la petición y solo al final el prompt. Si se invierte el orden, es fácil confundir un problema de configuración con un problema del modelo.

Este artículo desglosa cuatro categorías —401, 429, 529 overloaded y contexto excedido— con causas, pasos de diagnóstico y código de reintento reutilizable. Los modelos y los precios se rigen por la página de precios de modelos.

Nota: Anthropic y Claude son marcas de sus respectivos titulares. Los tipos de error y el comportamiento de la interfaz pueden cambiar según la versión; este artículo toma como ejemplo la situación habitual a octubre de 2026 y la documentación oficial prevalece.

1. Mira primero el código de estado, no cambies el prompt

Código Tipo de error Significado habitual ¿Reintentar?
400 invalid_request_error Problema de parámetros, formato o longitud de contexto Corregir la petición y reintentar
401 authentication_error Clave ausente, incorrecta o caducada No reintentar; corregir credenciales
403 permission_error La clave no tiene permiso de modelo o de proyecto No reintentar; revisar permisos
404 not_found_error Ruta o nombre de modelo incorrecto No reintentar; consultar la documentación
413 request_too_large Cuerpo de la petición demasiado grande Dividir y reintentar
429 rate_limit_error Frecuencia, concurrencia o tokens excedidos Reintentar con retroceso
500 api_error Error interno del servidor Reintentar con retroceso
529 overloaded_error Servidor sobrecargado Reintentar con retroceso

Conserva el request-id de las cabeceras de respuesta. Cuando pidas ayuda al proveedor, un ID de petición vale más que diez capturas de pantalla. En los registros guarda al menos la hora, el código de estado, el tipo de error, el nombre del modelo y el ID de la petición; nunca registres la clave completa ni contenido sensible.

2. 401: revisa primero las cabeceras y después la clave

Un 401 indica que la identidad no superó la verificación y no tiene relación con el saldo ni con las capacidades del modelo. Comprueba en este orden:

  1. ¿Usas x-api-key en lugar de Authorization: Bearer? La cabecera de autenticación de Claude Messages API no es Bearer.
  2. ¿Incluyes anthropic-version: 2023-06-01? A veces la ausencia de la cabecera de versión se manifiesta como un 400, pero añadirla desde el principio ahorra tiempo.
  3. ¿Hay espacios, saltos de línea o comillas de más antes o después de la clave? Es el problema más habitual al copiar desde una ventana de chat.
  4. ¿Se cargó realmente la variable de entorno? Puedes comprobar solo el prefijo, pero no imprimas la clave completa en los registros.
  5. ¿La clave fue revocada o pertenece a la organización o al proyecto actual?
  6. ¿La Base URL apunta al entorno correcto y la ruta es /v1/messages?
export ANTHROPIC_API_KEY="sk-tu-clave"

curl "https://ai.zhongshangqihang.com/v1/messages" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5-5",
    "max_tokens": 64,
    "messages": [{"role": "user", "content": "Responde solo OK"}]
  }'

Si este comando devuelve 200, la clave, la Base URL y el nombre del modelo son correctos. Si sigue devolviendo 401, prueba la misma clave en otro punto de entrada para distinguir si el problema está en la clave, en la configuración de la pasarela o en la red. Los nombres de modelo se rigen por precios de modelos.

3. 429: el límite de tasa no significa «saldo insuficiente»

Un 429 indica que la petición superó un límite de frecuencia o de cuota. Situaciones habituales:

  • Se superó el número de peticiones o de tokens por minuto.
  • La concurrencia aumentó de golpe y agotó la cuota en poco tiempo.
  • Varios servicios comparten una misma clave y compiten por la cuota.
  • Los reintentos no aplican retroceso: cuanto más fallan, más insisten, y crean una tormenta de reintentos.
  • Las salidas largas consumen muchos tokens de salida y dejan menos margen para la concurrencia.
Síntoma Causa posible Solución
429 concentrados en hora punta Picos de tráfico Colas y envío suavizado
429 con una clave usada por varios servicios Cuota compartida Separar claves por proyecto
Empeora después de reintentar Reintentos sin retroceso Retroceso exponencial con jitter
Las peticiones largas reciben 429 primero Alto consumo de tokens de salida Reducir max_tokens o la concurrencia

Revisa primero el retry-after de la respuesta, si existe, y decide cuánto esperar. El SDK distingue entre RateLimitError y APIStatusError; usa la comprobación por tipo, no la coincidencia de cadenas en el mensaje de error.

import random
import time
from anthropic import Anthropic, APIStatusError, RateLimitError

client = Anthropic()

def ask(prompt: str, retries: int = 4) -> str:
    for attempt in range(retries):
        try:
            resp = client.messages.create(
                model="claude-sonnet-5-5",
                max_tokens=1024,
                messages=[{"role": "user", "content": prompt}],
            )
            return resp.content[0].text
        except RateLimitError:
            wait = min(2 ** attempt, 20) + random.random()
            print(f"429, reintento {attempt + 1}, espera {wait:.1f}s")
            time.sleep(wait)
        except APIStatusError as exc:
            if exc.status_code >= 500:
                wait = min(2 ** attempt, 20) + random.random()
                print(f"{exc.status_code}, reintento en {wait:.1f}s")
                time.sleep(wait)
                continue
            raise
    raise RuntimeError("Se agotaron los reintentos")

Los reintentos solo sirven para errores transitorios. Si una operación de negocio ya produjo efectos secundarios, usa una clave de idempotencia o comprueba el estado para confirmar si se ejecutó antes de volver a enviarla.

4. 529 overloaded: sobrecarga del servidor, no de tu cuota

El error 529 overloaded_error indica que el servidor tiene una carga excesiva y normalmente no guarda relación con tu consumo. Se trata de forma distinta a un 429: en el 429 revisas tu concurrencia y tu cuota; en el 529 revisas el estado del servicio y reduces la presión.

  1. Confirma que el tipo de error es overloaded_error y no lo confundas con una clave inválida.
  2. Conserva el request-id y la hora para que el proveedor pueda localizar el incidente.
  3. Aplica retroceso exponencial con jitter aleatorio y fija un número máximo de reintentos; no reintentes a intervalos fijos.
  4. Reduce la concurrencia, usa colas para suavizar los picos y, si es necesario, pausa temporalmente las tareas no críticas.
  5. Prepara un modelo de respaldo o un canal alternativo, siempre que el negocio tolere cambios en la calidad de la salida.
  6. Si el problema dura más de lo previsto, contacta al proveedor y adjunta el ID de la petición.

Reintentar cada segundo sin control convierte un fallo pequeño en una avalancha. La política de reintentos debe tener un límite y también alertas; no puede ser un bucle infinito.

5. Contexto excedido: mide primero, divide después

El exceso de contexto suele devolver un 400 invalid_request_error, y el mensaje incluye prompt is too long. La causa no es que el modelo esté roto, sino que el presupuesto de entrada más salida supera la ventana de contexto del modelo.

Las fuentes habituales son: historial de mensajes sin recortar, herramientas que devuelven registros completos, documentos enteros insertados, demasiadas imágenes y un system prompt demasiado largo. El orden de actuación es:

  1. Cuantifica la entrada con count_tokens antes de la petición; no estimes por número de caracteres.
  2. Recorta el historial más antiguo y conserva el system prompt, los últimos turnos y un resumen.
  3. Recupera solo los fragmentos relevantes de los documentos; no insertes la base completa.
  4. Divide los documentos largos por capítulos y procesa por partes antes de fusionar los resultados.
  5. Comprime la salida de las herramientas y devuelve solo los campos necesarios; no arrastres la respuesta completa en cada turno.
  6. Deja espacio para la salida. max_tokens es el límite de salida, pero la entrada y la salida deben caber juntas en el contexto.
import os
from anthropic import Anthropic

client = Anthropic()
MODEL = "claude-sonnet-5-5"
LIMIT = int(os.environ.get("CONTEXT_BUDGET", "200000"))  # presupuesto propio, no el límite del modelo

def fit_messages(messages):
    while client.messages.count_tokens(model=MODEL, messages=messages).input_tokens > LIMIT:
        if len(messages) <= 2:
            raise ValueError("Un solo mensaje supera el presupuesto; divide el documento")
        messages = messages[2:]  # elimina el turno user/assistant más antiguo
    return messages

El LIMIT de este ejemplo es un presupuesto definido por el equipo, no una especificación del modelo. Conviene fijarlo algo por debajo del límite del modelo para dejar margen a la salida y a las llamadas de herramientas.

6. Tabla de orden para el diagnóstico

  1. Registra el código de estado, el tipo de error, el request-id, el nombre del modelo y la hora.
  2. Para 401 y 403, revisa credenciales y permisos; para 404, la ruta y el nombre del modelo.
  3. Para 400, revisa parámetros, longitud del contexto, formato de imágenes y tamaño del cuerpo.
  4. Para 429, revisa cuota, concurrencia, claves compartidas y tormentas de reintentos.
  5. Para 529, revisa el estado del servicio; aplica retroceso, reduce la concurrencia y prepara la degradación.
  6. Para 500, reintenta con retroceso; si persiste, contacta al proveedor con el ID de la petición.
  7. Después de cada incidente, añade monitorización y alertas; no esperes a que los usuarios lo detecten.

Preguntas frecuentes

¿Cuál es la diferencia entre 429 y 529?

Un 429 significa que tus peticiones superaron un límite de tasa o de cuota, así que debes revisar tu concurrencia, tus claves y tu consumo. Un 529 significa sobrecarga del servidor, así que debes aplicar retroceso, reducir la concurrencia y consultar el estado del servicio. Ambos requieren reintentos, pero la dirección del diagnóstico es distinta.

¿Por qué sigue fallando aunque haya reintentos?

Puede que no haya retroceso, que la concurrencia sea demasiado alta, que varios servicios compartan una clave o que la petición ya sea inválida por un 400. Los reintentos solo resuelven errores transitorios; no arreglan parámetros incorrectos ni problemas de permisos.

¿prompt is too long significa que el modelo está roto?

No. Indica que la entrada supera la ventana de contexto. Cuantifícala con count_tokens, recorta el historial, divide los documentos o aplica recuperación; no sigas añadiendo texto al prompt.

¿Cuántas veces conviene reintentar?

No hay una cifra universal. Fija un límite según la tolerancia del negocio, por ejemplo de 3 a 5 intentos, y a partir de ahí degrada o alerta. El intervalo debe aumentar y llevar jitter para evitar reenvíos simultáneos.

¿Cómo distingo un error de la pasarela de uno del proveedor?

Revisa primero el tipo de error y el request-id, y luego envía la misma petición al punto de entrada oficial y a la pasarela. Así podrás separar rápidamente si el problema es la clave, la red, la configuración de la pasarela o el servicio upstream.

Siguiente paso

Crea primero una clave de prueba en la pasarela de IA de ZSQH, reproduce una vez cada escenario (401, 429, 529 y contexto excedido) y después conecta la monitorización de producción. La disponibilidad de modelos y los precios figuran en precios de modelos.

Lecturas relacionadas: