Claude Code «API Error: bad_response_status_code»: cómo leer el estado que hay debajo

Este error le indica que la llamada falló y casi nada sobre el motivo. La información útil —el código de estado y el mensaje del proveedor— está a un indicador de depuración, y cada estado apunta a una solución diferente.

El error

terminal

API Error: bad_response_status_code

(no status, no provider message — the wrapper hides both)

Causas y soluciones de un vistazo

Causa	Solución
401 / 403 por debajo	Diferencia de credenciales o encabezados frente a una URL base personalizada. Compruebe qué variable de autenticación está definida.
404 por debajo	El id del modelo es desconocido para ese host o la URL base contiene un segmento de ruta adicional.
402 por debajo	La cartera de la puerta de enlace está vacía. Recargue saldo; no hay ningún problema con la configuración del cliente.
429 / 529 por debajo	Límite de solicitudes alcanzado o proveedor ascendente saturado. Reintente con retroceso en lugar de reconfigurar.
Un cuerpo no JSON con un 200	Un portal cautivo, un proxy corporativo o una página de error. El estado puede ser correcto y el cuerpo seguir siendo inutilizable.

Convierta la envoltura en un error real

La salida de depuración de Claude Code imprime la solicitud y la respuesta del proveedor ascendente. Ejecute una llamada fallida con ella activada y lea la línea de estado; todo lo que viene después depende de lo que indique.

debug.sh

claude --debug 2>&1 | tee claude-debug.log

grep -iE 'status|http/|error' claude-debug.log | head -20

Reproduzca la misma llamada con curl

Extraiga la URL base y las credenciales de la herramienta y emita la solicitud directamente. Esto separa en un solo paso «el host nos rechaza» de «el cliente está mal formado», y el cuerpo sin procesar suele nombrar el problema en un lenguaje claro que la envoltura descartó.

reproduce.sh

curl -i "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":16,
       "messages":[{"role":"user","content":"ping"}]}'

Compruebe que la URL base no tenga una ruta final

Claude Code añade su propia ruta `/v1/...`. Una URL base que ya termina en `/v1` produce `/v1/v1/messages`, a lo que cualquier host responde con un 404, envuelto una vez más como bad_response_status_code. Configure solo el origen.

base-url.sh

# Wrong — doubles the version segment
export ANTHROPIC_BASE_URL="https://api.kunavo.com/v1"

# Right — origin only
export ANTHROPIC_BASE_URL="https://api.kunavo.com"

Si llamas a través de Kunavo

Con Kunavo, los dos estados que conviene reconocer de inmediato son 402 y 401: 402 significa que la cartera no puede cubrir la solicitud —es un problema de saldo, no de configuración— y 401 significa que Kunavo no recibió una clave sk-kn- utilizable. Lee la clave tanto de Authorization: Bearer como de x-api-key, así que compruebe qué envió realmente Claude Code: una clave en ANTHROPIC_API_KEY necesita una aprobación única en una sesión interactiva y se ignora una vez rechazada, mientras que ANTHROPIC_AUTH_TOKEN se utiliza de inmediato. Ambos estados devuelven un cuerpo JSON que indica el motivo, por lo que el registro de depuración es concluyente y no meramente orientativo. Las solicitudes fallidas no se facturan. Qué variable definir y por qué se explica en la guía de variables de autenticación.

Preguntas frecuentes

¿Este error puede ser alguna vez un error del propio Claude Code?

Rara vez. Es una envoltura a nivel de transporte: algo respondió y la respuesta no fue un éxito. Reproducirlo con curl lo resuelve; si curl también falla, el cliente no es el problema.

Funciona con la API oficial, pero no con mi puerta de enlace.

Entonces la diferencia está en las credenciales o en la URL base, no en la herramienta. Compruebe el encabezado de autenticación que espera la puerta de enlace y si la URL base ya contiene /v1.

¿Debo reintentar automáticamente?

Solo después de conocer el estado. Reintentar un 401 o 404 no tiene sentido; reintentar un 429 o 529 con retroceso es correcto.

Guías relacionadas

Encontrarás más detalles sobre el significado de los errores en referencia de errores; obtener una clave lleva un minuto mediante registro y la guía de autenticación.