Cuando Claude Code se conecta a una API de terceros, la mayoría de los errores no vienen del modelo, sino de la configuración, la autenticación o la red: un 401 apenas terminas de configurar, un 404 después de cambiar la Base URL, un 429 a mitad de una tarea o una tarea larga que se queda bloqueada hasta agotar el tiempo de espera. El orden de resolución es: primero el código de estado y el tipo de error, después el request-id y solo al final el prompt. Este artículo desglosa los casos 401, 404, 429, contexto excedido y timeouts, con pasos de diagnóstico, una lista de datos para los logs y código de ejemplo. Los modelos y la facturación se rigen por precios de modelos.

Nota: Claude, Claude Code y Anthropic 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. Separa por capas: en cuál ocurrió el error

Una petición atraviesa cuatro capas: cliente, red, gateway y modelo de origen. Un mismo 401 puede ser una clave incorrecta o un encabezado de autenticación que no coincide; un mismo 404 puede ser una ruta con /v1 de más o un nombre de modelo inexistente. Separar por capas evita cambiar la configuración repetidamente en la dirección equivocada.

Código Tipo de error Causa habitual Qué hacer
400 invalid_request_error Parámetros, formato, longitud de contexto o límite de gasto Corregir la petición o ajustar el límite y reintentar
401 authentication_error Clave ausente, incorrecta, expirada o encabezado incompatible Corregir credenciales; no reintentar
402 billing_error Problema con la facturación o los datos de pago Revisar la facturación
403 permission_error La clave no tiene permiso de modelo o de proyecto Revisar permisos
404 not_found_error Ruta o nombre de modelo incorrecto Revisar la Base URL y el nombre del modelo
413 request_too_large El cuerpo de la petición supera el límite de la interfaz Dividir la petición
429 rate_limit_error Frecuencia, concurrencia o límite de gasto Reintentar con retroceso
500 api_error Error interno del servidor Reintentar con retroceso
504 timeout_error Tiempo de procesamiento agotado Usar streaming o dividir en lotes
529 overloaded_error Servidor sobrecargado Retroceder y reducir concurrencia

Conserva el request-id de los encabezados de respuesta; el cuerpo del error también suele incluir request_id. Para que el proveedor investigue, un ID de petición vale más que diez capturas de pantalla. En los logs registra al menos hora, código de estado, tipo de error, nombre del modelo e ID de petición; no registres la clave completa ni contenido sensible.

2. 401 y 403: encabezados de autenticación y claves

Un 401 significa que la identidad no superó la verificación y no tiene relación con el saldo ni con la capacidad del modelo. Claude Code tiene dos variables que se confunden con facilidad: ANTHROPIC_API_KEY se envía como X-Api-Key; ANTHROPIC_AUTH_TOKEN se envía como Authorization: Bearer. Si el gateway solo acepta una, usar la otra produce un 401 constante; confirma primero cuál exige y no exportes las dos a la vez.

Otras causas frecuentes: espacios, saltos de línea, comillas o caracteres de ancho completo antes o después de la clave; una clave eliminada, expirada o perteneciente a otro espacio de trabajo; una Base URL que apunta al entorno equivocado; tener a la vez el inicio de sesión de una suscripción y una API Key; o una red corporativa o un proxy que reescribe el encabezado de autenticación.

Un 403 suele ser un problema de permisos: la clave no tiene habilitado ese modelo, no tiene permiso de proyecto, está bloqueada por una lista de IP permitidas o la política del espacio de trabajo no lo permite. Ante un 403 no reintentes; revisa primero la autorización de modelos y la política de acceso en la consola.

Aislamiento rápido: usa la misma clave y la misma Base URL para llamar directamente a /v1/messages. Si la llamada directa funciona y Claude Code falla, el problema está en la configuración del cliente; si la llamada directa también falla, el problema está en la clave, el gateway o la red.

3. 404: ruta de la Base URL y nombre del modelo

Hay dos tipos de 404: ruta incorrecta o recurso inexistente. Claude Code usa Anthropic Messages API y normalmente configura la Base URL como dirección raíz, y el cliente añade /v1/messages. Si la Base URL ya incluye /v1, la ruta real puede convertirse en /v1/v1/messages.

Revisa en este orden:

  1. Confirma el protocolo: Claude Code usa Anthropic Messages, no OpenAI Chat Completions.
  2. Comprueba si la Base URL tiene /v1 de más o de menos. Claude Code suele usar la dirección raíz; los clientes compatibles con OpenAI suelen usar una dirección con /v1.
  3. Revisa la barra final y las mayúsculas para evitar dobles barras o rutas truncadas.
  4. Copia el nombre actual del modelo desde precios de modelos; los alias del gateway pueden diferir de los nombres oficiales.
  5. Prueba con una petición mínima para descartar el proxy y la caché del cliente.

Si el mensaje es model not found, revisa el nombre del modelo y los permisos; si es not_found_error y la ruta es claramente incorrecta, revisa la Base URL.

4. 429: límites de tasa, cuota y tormenta de reintentos

Un 429 indica que las peticiones superaron un límite de velocidad, concurrencia o gasto. Causas habituales: se excedió el número de peticiones o de tokens por minuto; varios servicios comparten una clave; los reintentos no aplican retroceso y forman una tormenta; se alcanzó el límite de gasto de la cuenta o del espacio de trabajo; un aumento repentino de tráfico activó una limitación acelerada.

Algunos 429 provocados por el límite de gasto no incluyen retry-after; esperar no los resuelve y hace falta ajustar el límite o recargar. Revisa primero retry-after: si existe, espera ese tiempo; si no, usa retroceso exponencial con jitter aleatorio y fija un número máximo de reintentos. No reintentes 401, 403, 404 ni 400.

Ojo con los reintentos predeterminados del SDK: el SDK oficial de Anthropic reintenta dos veces los errores de conexión, los 429 y los 5xx; si la capa de negocio añade otra, el número real de peticiones se multiplica. Planifica max_retries junto con los reintentos de negocio.

Un 429 y un 529 no son lo mismo: ante un 429 revisa tu concurrencia, tu clave y tu cuota; un 529 indica sobrecarga del servidor y conviene retroceder, reducir concurrencia y consultar el estado del servicio.

5. 400 y 413: contexto excedido y peticiones demasiado grandes

Cuando se excede el contexto suele devolverse un 400 invalid_request_error con un mensaje como prompt is too long. La causa no es un fallo del modelo, sino que el presupuesto de entrada más salida supera la ventana de contexto.

Orden de tratamiento:

  1. Antes de enviar, cuantifica la entrada con count_tokens; no estimes por número de caracteres.
  2. Recorta el historial más antiguo y conserva el sistema, las últimas rondas y un resumen.
  3. Recupera primero los fragmentos relevantes de los documentos; no incluyas la base completa.
  4. Divide los documentos largos por capítulos, procésalos por partes y combina después los resultados.
  5. Comprime la salida de las herramientas y devuelve solo los campos necesarios.
  6. Deja espacio para la salida. max_tokens solo limita la salida; no resuelve una entrada demasiado larga.

El 413 request_too_large indica que el cuerpo de la petición es demasiado grande, algo distinto de la longitud del contexto. Es especialmente frecuente cuando las imágenes se incluyen en base64; puedes comprimirlas, usar una interfaz de carga de archivos o dividir la petición.

No todos los 400 son problemas de contexto. Un parámetro no admitido por el modelo actual, una configuración de thinking no válida o un límite de gasto también pueden devolver 400. Lee el type y los campos concretos del mensaje de error.

6. Timeouts y cortes de flujo: streaming, proxy y SSL

El tiempo de espera de cada petición de Claude Code se controla con API_TIMEOUT_MS, cuyo valor predeterminado es 600000 milisegundos, es decir, 10 minutos. En redes lentas o con proxy puedes aumentarlo, pero no lo hagas indefinidamente; de lo contrario, un fallo tarda mucho en manifestarse.

Para tareas largas, prioriza la salida en streaming o la interfaz por lotes. Una petición sin streaming que se prevea de más de 10 minutos puede sufrir cortes de conexión inactiva y aparecer como bloqueo o timeout. Una petición en streaming recibe datos de forma continua y mantiene la conexión más estable.

Atención: una petición en streaming puede devolver primero HTTP 200 y después enviar un evento error dentro del flujo SSE. Un cliente que solo mira el código de estado interpretará el fallo como éxito. Hay que analizar los eventos de error del flujo y marcar la parte generada como incompleta.

Los problemas de proxy y certificados también se manifiestan como timeouts: un proxy corporativo exige configurar HTTPS_PROXY o HTTP_PROXY; la interceptación TLS empresarial requiere confiar en el certificado CA correspondiente, y en clientes Node la práctica habitual es definir NODE_EXTRA_CA_CERTS; DNS, IPv6, cortafuegos y MTU también pueden causar conexiones inestables, y cambiar de red o usar un punto de acceso móvil ayuda a identificarlo. Si el gateway tarda mucho en enviar el primer byte, revisa CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS.

7. Logs y lista de soporte

Al diagnosticar no dejes solo un “da error”. Recoge la información de esta lista:

  1. Hora del suceso, zona horaria y duración.
  2. claude --version y sistema operativo.
  3. Base URL (conserva el dominio, sin la clave completa).
  4. Nombre del modelo, si se usó streaming, duración de la petición y número de reintentos.
  5. Código de estado HTTP, tipo de error y mensaje completo.
  6. request-id, que puede aparecer en encabezados y en el cuerpo.
  7. Alcance: una persona, una red, un proyecto o todo el equipo.
  8. Reproducción mínima: un curl o un repositorio mínimo, y el resultado de la misma petición contra el punto de entrada oficial.

El enmascarado de logs debe ser concreto: deja solo los cuatro primeros y los cuatro últimos caracteres de la clave, y trata los prompts y el contenido del código según la normativa de la empresa.

8. Ejemplo: decide si reintentar según el tipo de error

El ejemplo siguiente solo reintenta 429, 5xx y timeouts de red; ante 401 y 404 falla de inmediato para no convertir un problema de configuración en una tormenta de reintentos. La Base URL y el nombre del modelo se leen de variables de entorno.

import os
import random
import time

from anthropic import (
    Anthropic,
    APIConnectionError,
    APIStatusError,
    APITimeoutError,
    AuthenticationError,
    NotFoundError,
    RateLimitError,
)

client = Anthropic(
    base_url=os.environ["ANTHROPIC_BASE_URL"],
    auth_token=os.environ["ANTHROPIC_AUTH_TOKEN"],
)

def ask(prompt: str, retries: int = 4) -> str:
    for attempt in range(retries):
        try:
            resp = client.messages.create(
                model=os.environ["ANTHROPIC_MODEL"],
                max_tokens=512,
                messages=[{"role": "user", "content": prompt}],
            )
            return resp.content[0].text
        except AuthenticationError as exc:
            raise SystemExit(f"401: revisa la clave y el encabezado, request-id={exc.request_id}") from exc
        except NotFoundError as exc:
            raise SystemExit(f"404: revisa la Base URL y el modelo, request-id={exc.request_id}") from exc
        except RateLimitError:
            wait = min(2 ** attempt, 20) + random.random()
            print(f"429: reintento en {wait:.1f}s")
            time.sleep(wait)
        except (APITimeoutError, APIConnectionError):
            wait = min(2 ** attempt, 10) + random.random()
            print(f"Timeout o fallo de conexión: reintento en {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; aplicar degradación o alerta")

print(ask("Responde solo OK"))

Si el gateway usa X-Api-Key en lugar de Bearer, cambia auth_token= por api_key= o ajusta según la documentación del cliente. El ejemplo no define max_retries explícitamente, así que el SDK seguirá reintentando por defecto; en producción conviene configurarlo de forma unificada.

Preguntas frecuentes

¿Un 401 siempre significa que la clave es incorrecta?

No. Un encabezado de autenticación incompatible, una Base URL que apunta al entorno equivocado o un proxy que reescribe encabezados también devuelven 401. Prueba primero con la misma clave y la misma Base URL de forma directa y después revisa las variables del cliente.

Cambié de modelo y el 404 continúa, ¿qué hago?

Revisa sobre todo la ruta de la Base URL. Claude Code suele usar la dirección raíz y el cliente añade /v1/messages; una dirección con /v1 produce un doble /v1. Después confirma que el nombre del modelo coincida con la lista del gateway.

¿Un 429 se recupera siempre después de esperar?

No necesariamente. Los límites de velocidad suelen recuperarse, pero un 429 provocado por el límite de gasto puede no incluir retry-after; esperar no sirve y hay que ajustar el límite o recargar. Decide después de revisar el tipo de error y los encabezados.

Si una petición en streaming devuelve 200 y luego se corta, ¿cuenta como éxito?

No. Una respuesta en streaming puede enviar un evento de error por SSE después del 200. El cliente debe analizar el flujo de eventos y confirmar que recibió el evento de finalización normal; de lo contrario, debe marcar el resultado como incompleto y reintentar o alertar.

¿Cuantos más reintentos, más estable?

No. Los reintentos solo resuelven errores transitorios; un número excesivo amplifica fallos y costos. Define un máximo, retroceso exponencial y jitter aleatorio, y distingue errores reintentables de los que no lo son; antes de reenviar una operación con efectos secundarios, confirma si ya se ejecutó.

Próximos pasos

Crea primero una clave de prueba en ZSQH AI Gateway y practica una vez cada caso: 401, 404, 429 y timeout; después conecta el monitoreo de producción. La disponibilidad de modelos y la facturación se rigen por precios de modelos.

Lecturas relacionadas: