Errores de Claude Code: cómo distinguir 401, 429, 529 y los errores de instalación

Los errores de Claude Code son de dos tipos principales, y la mayoría de los resultados de búsqueda solo cubren uno de ellos. Los errores del cliente durante la instalación o la ejecución y los errores de API que aparecen al llamar al modelo tienen causas y soluciones completamente distintas. Este artículo se centra en el segundo grupo —401, 429 y 529—, porque son los errores que suelen aparecer primero al pasar de una suscripción a una clave de API.

Las cadenas de error aparecen en inglés en todos los países. A continuación, se mantienen literalmente y solo se explican en español.

Primero, divide la causa en tres posibilidades en 30 segundos

Antes de cambiar la configuración, envía una solicitud directa al endpoint. Esta única comprobación distingue entre «problema del cliente / problema de autenticación / problema del servidor».

# 오류가 클라이언트 문제인지 엔드포인트 문제인지 30초 만에 가르는 방법.
# 200이 돌아오면 키와 주소는 정상이고, 남은 문제는 Claude Code 설정입니다.
curl -sS https://api.kunavo.com/v1/messages \
  -H "Authorization: Bearer sk-kn-..." \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-haiku-4-5","max_tokens":16,
       "messages":[{"role":"user","content":"ping"}]}'

401 — el problema suele ser el encabezado, no la clave

Si el 401 continúa aunque hayas generado varias claves nuevas, sospecha de la forma en que se envía, no del valor. Claude Code envía ANTHROPIC_AUTH_TOKEN mediante el encabezado Authorization: Bearer, y ANTHROPIC_API_KEY mediante el encabezado x-api-key. Las puertas de enlace suelen esperar el primero, por lo que intercambiar ambas variables provoca un 401 incluso con una clave válida.

También es habitual que ambas variables sigan configuradas. Elimina una, abre un shell nuevo y vuelve a intentarlo. La diferencia entre ambas variables se explica en Diferencia entre ANTHROPIC_AUTH_TOKEN y ANTHROPIC_API_KEY.

429 — dos 429 diferentes

El número es el mismo, pero la causa es completamente distinta. Si utilizas una suscripción, has alcanzado el límite de la ventana de sesión y no hay otra opción que esperar a que se restablezca; pasar a un plan superior tampoco ayuda en ese momento. Si utilizas una clave de API, se trata de un límite de solicitudes por segundo o de procesamiento de tokens, que normalmente se resuelve reintentando con retroceso exponencial.

Puedes distinguirlos directamente comprobando si ANTHROPIC_BASE_URL está configurado. Si lo está, estás usando una clave, no una suscripción. La estructura de los límites de la suscripción y las opciones al superarlos se explican en Precios de Claude Code.

529 overloaded_error — un error que no es tuyo

529 significa que el servidor de modelos ascendente está temporalmente sobrecargado. Ni el contenido de la solicitud, ni la clave, ni el saldo son la causa, por lo que no es un error que pueda eliminarse corrigiendo la configuración. La única respuesta es reintentar, y el retroceso exponencial tiene una tasa de éxito mucho mayor que reintentar inmediatamente.

Si utilizas una puerta de enlace con conmutación por error automática, cuando un proveedor ascendente devuelve 529 la solicitud pasa a otra ruta, por lo que la frecuencia percibida disminuye. La explicación detallada para lectores anglófonos está en Cómo responder a 529 overloaded_error.

Continuar trabajando al alcanzar el límite de la suscripción

Si el 429 procede de la suscripción, puedes pasar solo esa sesión a una clave en lugar de esperar. No necesitas cancelar la suscripción: mientras las dos variables siguientes estén configuradas, se facturará mediante la clave, y al eliminarlas volverás al funcionamiento original.

# Claude Code를 구독 대신 API 키로 돌릴 때 쓰는 두 줄.
# 이 두 변수가 설정돼 있는 동안에는 구독 한도가 적용되지 않습니다.
export ANTHROPIC_BASE_URL=https://api.kunavo.com
export ANTHROPIC_AUTH_TOKEN=sk-kn-...

# Claude Code의 기본 모델과 opus·sonnet 별칭은 Anthropic의 최신 모델을 가리키므로,
# Kunavo가 아직 제공하지 않는 모델이 호출돼 404가 나지 않도록 모델을 고정합니다.
# sonnet 별칭이 부르는 Sonnet 5.5는 Kunavo가 제공하지 않아, 고정하지 않으면
# /model sonnet, opusplan의 실행 단계, sonnet으로 지정한 서브에이전트에서 404가 납니다.
# Opus 5.5는 Claude Code v2.1.280 이상이 필요합니다(이전 버전이면 claude update로 업데이트).
export ANTHROPIC_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5-5
export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5

# 백그라운드 작업을 가장 싼 모델로 보내는 한 줄 — 매 세션 효과가 있습니다.
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5

Las tarifas se leen directamente del catálogo: Claude Sonnet 5 cuesta $1.40 / $7.00 por 1M de tokens, y Claude Haiku 4.5 cuesta $0.70 / $3.50. Como se descuenta del saldo prepagado, no hay costes en los meses en que no trabajas. Los métodos de pago y el registro de tarjetas nacionales se explican en Precios y pagos de Claude API.

Los errores durante la instalación son independientes

Los problemas de instalación suelen deberse a la versión de Node.js o a permisos de instalación global, y pertenecen a una categoría distinta de los tres errores anteriores. Primero comprueba si claude --version se muestra correctamente. Si aparece, la instalación terminó y el problema posterior está relacionado con la autenticación o la red. Mezclar ambas categorías es la forma más lenta de abordarlas.

Preguntas frecuentes