Tabla de errores: Claude Code y Codex sobre una API de terceros

Cómo usar esta página

No empieces buscando el texto del error. Empieza averiguando qué capa ha fallado. Casi todos los errores de los clientes de IA vienen de una de estas cinco:

1. Red: la petición no llegó a salir de tu máquina
2. Autenticación: llegó, pero la key fue rechazada
3. Protocolo: la key estaba bien, la ruta o el formato no
4. Modelo: el protocolo funcionó, el modelo no existe
5. Contexto: el modelo está corriendo, la entrada es demasiado larga

Las capas importan porque cada una tiene una solución completamente distinta, y el texto del error rara vez te dice en cuál estás.

Diagnóstico por estado HTTP

Estos comandos comprueban la lista de modelos y tres protocolos e indican el estado HTTP de cada solicitud:

Define tu propia API key de KimiSeek en el mismo terminal donde ejecutarás curl y sustituye el valor de ejemplo. Las credenciales guardadas en el cliente no rellenan automáticamente esta variable del shell:

# Replace the placeholder with your own key from the dashboard.
export KIMISEEK_API_KEY="ks-your-key"

# Inspect each HTTP status and error body; a model list does not prove sufficient balance.
# 1. Is the key valid at all? (lists models)
curl -sS --max-time 30 -w '\nHTTP %{http_code} /v1/models\n' https://api.kimiseek.app/v1/models \
  -H "Authorization: Bearer ${KIMISEEK_API_KEY:?Set KIMISEEK_API_KEY before running this command}"

# 2. OpenAI Chat Completions
curl -sS --max-time 30 -w '\nHTTP %{http_code} /v1/chat/completions\n' https://api.kimiseek.app/v1/chat/completions \
  -H "Authorization: Bearer ${KIMISEEK_API_KEY:?Set KIMISEEK_API_KEY before running this command}" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-v4-pro-0813","messages":[{"role":"user","content":"ping"}],"max_tokens":8}'

# 3. Anthropic Messages (the protocol Claude Code speaks)
curl -sS --max-time 30 -w '\nHTTP %{http_code} /v1/messages\n' https://api.kimiseek.app/v1/messages \
  -H "x-api-key: ${KIMISEEK_API_KEY:?Set KIMISEEK_API_KEY before running this command}" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-v4-pro-0813","max_tokens":8,"messages":[{"role":"user","content":"ping"}]}'

# 4. OpenAI Responses (the protocol Codex speaks)
curl -sS --max-time 30 -w '\nHTTP %{http_code} /v1/responses\n' https://api.kimiseek.app/v1/responses \
  -H "Authorization: Bearer ${KIMISEEK_API_KEY:?Set KIMISEEK_API_KEY before running this command}" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-v4-pro-0813","input":"ping","max_output_tokens":16}'

Lee el estado HTTP tras cada respuesta y los campos error.code, error.type y message del cuerpo. El paso que falla no determina si el protocolo está implementado. Una lista de modelos con 200 valida la clave, no el saldo: una cuenta sin saldo puede recibir 200 en el paso 1 y 402 en el paso 2.

Lado de Claude Code

Sin credenciales

Invalid API key · Please run /login

Esto significa que Claude Code no encontró ninguna credencial. Comprueba si ANTHROPIC_AUTH_TOKEN está definida en el shell que lo lanzó: un error clásico es exportarla en una terminal y arrancar el cliente en otra.

401 no autorizado

API Error: 401 {"type":"error","error":{"type":"authentication_error","message":"invalid api key"}}

Causas, por orden de probabilidad:

1. La key se copió con un espacio o un salto de línea de más
2. La key fue revocada o su cuota está agotada
3. ANTHROPIC_API_KEY está definida pero vacía, así que el cliente recurre a la sesión iniciada

403 forbidden

API Error: 403 {"type":"error","error":{"type":"forbidden","message":"invalid x-api-key"}}

Yendo directo, esto suele significar que la key no es válida. A través de una pasarela, la causa más habitual es un desajuste de cabecera: algunas pasarelas solo aceptan Authorization: Bearer, otras solo x-api-key. KimiSeek acepta ambas, pero si tienes otro proxy en medio, la cabecera puede acabar reescrita.

model not found

API Error: 400 {"type":"error","error":{"type":"invalid_request_error","message":"model: deepseek-v4-flash-0731 not found"}}

Dos posibilidades: un nombre de modelo mal escrito o un modelo retirado. Un id de modelo retirado sigue devolviendo not found en lugar de avisar de que se retiró, y esa es la trampa que más tiempo consume: acabas revisando la configuración cuando la respuesta real es que el modelo cambió de generación.

Sustitúyelo por un id real de la página de modelos.

El stream se corta a mitad

API Error: stream disconnected before completion: stream closed before completion

Se cortó una conexión de streaming en pleno vuelo. Revisa en este orden:

1. Si hay un proxy HTTP local (HTTPS_PROXY) interceptando
2. Si la red corporativa corta por timeout las respuestas largas
3. Si saltó un límite del servidor por petición

El tiempo de espera de la petición al proveedor es de 600 segundos para /v1/messages (Claude Code) y de 175 segundos para /v1/responses (Codex). El cliente o un proxy intermedio puede cerrar la conexión antes; comprueba el endpoint utilizado y los detalles del error.

Desbordamiento de contexto

API Error: 400 {"type":"error","error":{"type":"invalid_request_error","message":"prompt is too long: 210000 tokens > 200000 maximum"}}

Fíjate en que el 200000 de aquí es el límite del cliente o del modelo, no necesariamente el que esperabas. En DeepSeek V4 Pro el límite real es 1M, así que ver 200000 significa que la petición no llegó al modelo que crees, o que el cliente truncó según la especificación de Claude.

Lado de Codex

401 Missing bearer

■ unexpected status 401 Unauthorized: Missing bearer

env_key en config.toml es solo un nombre de variable; el valor tiene que estar en el entorno. Este error es «nombraste la variable, pero está vacía».

404 Not Found

■ unexpected status 404 Not Found

Ocho de cada diez veces a base_url le falta /v1. Codex construye base_url + "/responses", así que sin /v1 da contra una página web.

Tras comprobar base_url, revisa también si el cuerpo indica un modelo no encontrado. Si realmente falta /v1/responses, utiliza una pasarela o una capa de conversión compatible; el Codex actual rechaza wire_api = "chat". Consulta la guía de Codex.

Interrupción del stream

■ stream disconnected before completion

El mismo problema de streaming que en Claude Code, pero Codex es más sensible porque su bucle de ejecución depende de un flujo de eventos completo. Con una red inestable, cambia de red en lugar de reintentar.

Dos fallos de red típicos

fetch failed
ECONNREFUSED 127.0.0.1:7890

fetch failed es el error de red genérico de Node y por sí solo no aporta información. La línea útil es ECONNREFUSED: si apunta a un puerto local como 127.0.0.1:7890, significa que un proxy local se hizo cargo de la petición y el proxy no está corriendo o sus reglas están mal.

Este es el fallo que más veces se diagnostica mal como «la pasarela está caída». La prueba: si curl funciona y el cliente no, el entorno del shell del cliente es distinto del de curl.

El mismo error, causas distintas

Este es el modelo mental que más importa cuando hay una pasarela en medio:

Qué incluir cuando pides ayuda

Cuatro cosas, todas, o nadie podrá diagnosticarlo:

1. La línea de error completa, no una captura recortada
2. El resultado de la sonda curl por capas: cuál de los cuatro pasos falló
3. Las versiones del cliente (claude --version, codex --version)
4. El id de modelo y la Base URL en uso, con la key tapada

Verificación

• Verificado: 2026-10-26
• Los ejemplos ayudan a localizar el fallo; los mensajes pueden variar según la versión del cliente. Indica la versión instalada al informar del problema. La configuración de Codex se comprobó con 0.154.0.