Después de conectar una API personalizada en Chatbox, la mayoría de los errores no significan que «el modelo esté roto», sino que pertenecen a cuatro categorías: identidad incorrecta, dirección o modelo incorrectos, cuota o concurrencia agotadas, o problemas de red y TLS. Clasificar antes de verificar es mucho más eficaz que reinstalar el cliente una y otra vez.

Este artículo aborda los errores 401, 404 (incluido model not found), 429 y los fallos de conexión, y añade los cortes de streaming, la sincronización entre dispositivos y la recolección de evidencia en registros. Los nombres de la interfaz dependen de tu versión actual de Chatbox; los modelos y precios se consultan en la página de precios de modelos.

Nota: Chatbox es un producto y una marca de su titular; este artículo solo ofrece una explicación técnica de diagnóstico y no representa ninguna relación de afiliación. Los nombres de campo y los valores predeterminados pueden variar entre versiones.

1. Guarda primero la evidencia y después clasifica

Síntoma Código o error habitual Primera interpretación Qué revisar primero
401 (credenciales rechazadas) invalid_api_key, respuesta vacía Clave o cabecera de la solicitud Si la clave está completa y corresponde a esa dirección
404 / model not found not_found_error Ruta o ID del modelo Host, ruta de API, ID del modelo
429 Too Many Requests rate_limit_error, insufficient_quota Límite de peticiones o saldo Consumo, concurrencia, facturación
Failed to fetch / Network Error Sin código de estado Red inaccesible DNS, proxy, firewall, TLS
5xx server_error Fallo del upstream o del gateway Reintentar y registrar el request id

Antes de diagnosticar, anota la hora del incidente, la versión de Chatbox, el código HTTP, el cuerpo de la respuesta y el request ID. Sin esos datos solo puedes adivinar; con ellos puedes determinar si el problema está en el cliente, en la red o en el servidor.

2. 401: la clave no es reconocida

Un 401 indica que el servidor no reconoce esta clave. Las causas más frecuentes son:

  • Al copiar se introdujeron espacios, saltos de línea o caracteres de ancho completo; al pegar parecen iguales, pero no lo son.
  • Se usó una clave de licencia de Chatbox AI como clave API y se introdujo en el proveedor personalizado.
  • La clave fue eliminada, rotada o el proyecto al que pertenece está desactivado.
  • Se envía una clave del proveedor A a la dirección del proveedor B.
  • La solicitud pasa por un proxy corporativo que devuelve una página de inicio de sesión con 401 y un cuerpo HTML en lugar de JSON.

Confirma primero que el modo de API es compatible con OpenAI y vuelve a pegar la clave. No decidas por «parece igual»: prueba directamente fuera del cliente:

export ZSQH_API_KEY="sk-tu-clave"

curl -sS "https://ai.zhongshangqihang.com/v1/chat/completions" \
  -H "Authorization: Bearer $ZSQH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"tu-modelo-id","messages":[{"role":"user","content":"Responde solo OK"}]}' \
  -w "\nHTTP %{http_code}\n"

Si devuelve 200 y choices, la clave y la dirección son válidas; si sigue dando 401, el problema está en la copia de la clave, en sus permisos o en el proxy. Un 403 suele significar «te reconozco, pero no puedes usar este modelo»; no lo confundas con un 401 ni te dediques a cambiar claves una y otra vez.

3. 404 y model not found: revisa la dirección y el modelo por separado

Hay dos tipos de 404: la ruta no existe o el modelo no existe. El primero se revisa en la URL; el segundo, en el ID del modelo. Chatbox separa el host de API y la ruta de API, y el error más común es duplicar /v1: el host ya termina en /v1 y la ruta también incluye /v1/chat/completions, de modo que la solicitud final queda como /v1/v1/chat/completions.

El criterio es único: en la dirección final de la solicitud, /v1 debe aparecer una sola vez. Si el host es https://ai.zhongshangqihang.com, la ruta puede quedar vacía o completarse según la documentación de tu versión; si el host es .../v1, no repitas la ruta. Guarda el cambio y vuelve a probar con el botón «Comprobar» o con curl.

model_not_found no depende de la ruta. El ID del modelo distingue mayúsculas, sufijos de versión y prefijos de proveedor, y debe copiarse de la página de precios de modelos o del panel. Al agregar un modelo manualmente, confirma también que el tipo sea chat y que las capacidades marcadas coincidan con las reales; de lo contrario, el modelo puede no aparecer o fallar en la primera llamada.

Que falle «Obtener lista de modelos» tampoco implica necesariamente un error de configuración. Algunos gateways no exponen la interfaz de lista; si escribes manualmente el ID correcto, la conversación puede funcionar con normalidad.

4. 429: límite de peticiones, concurrencia y saldo

Un 429 tiene dos significados: las solicitudes van demasiado rápido o no queda cuota. En las interfaces compatibles con OpenAI es habitual rate_limit_error para el primer caso e insufficient_quota para el segundo. Ambos pueden ser 429, pero la solución es opuesta.

  • Demasiado rápido: reduce la concurrencia y el número de sesiones y clientes abiertos al mismo tiempo; un contexto largo amplía el consumo de tokens.
  • Sin cuota: revisa el consumo y la facturación del gateway, recarga o cambia de clave; reintentar sin más no lo resolverá.
  • Si la respuesta incluye la cabecera Retry-After, espera ese tiempo; si no, aplica retroceso exponencial con un componente aleatorio.
  • No pulses «Comprobar» ni reenvíes el mensaje repetidamente en Chatbox; en poco tiempo se acumulan solicitudes.
  • Una misma clave compartida entre varios dispositivos y ventanas también comparte la cuota de concurrencia.

Si el 429 solo aparece en conversaciones largas, comprime primero el contexto o abre una sesión nueva y después confirma la ventana de contexto del modelo. El ajuste de «número máximo de mensajes de contexto» puede reducirse, pero solo alivia la presión del contexto; no sustituye la gestión de consumo y concurrencia.

5. Fallo de conexión: DNS, proxy, SSL y firewall

Failed to fetch, Network Error o una rueda que gira sin fin indican que la solicitud no obtuvo una respuesta válida. Comprueba primero que el navegador abra la página web y después prueba el mismo dominio con curl. Si curl también falla, el problema está en la red o en el gateway; si curl funciona y Chatbox no, suele estar en el proxy del cliente, en el ensamblado de la ruta o en la confianza del certificado.

  • Red corporativa: el firewall o la puerta de seguridad pueden bloquear dominios desconocidos; pide a TI que los permita.
  • Proxy: el proxy del sistema, la VPN y el interruptor de proxy de Chatbox pueden superponerse; deja solo una capa y no pongas la dirección del proxy en el host de API.
  • TLS: self signed certificate, UNABLE_TO_VERIFY_LEAF_SIGNATURE o un certificado caducado son habituales en proxys corporativos que descifran tráfico; instala el certificado raíz de la empresa en lugar de desactivar la validación.
  • Reloj del sistema: una desviación grande hace fallar la validación del certificado.
  • Red del celular: si Wi-Fi y datos móviles dan resultados distintos, el problema está en la red local o en DNS.

Si el error solo aparece en una máquina, compara primero el proxy del sistema, el archivo hosts, DNS y los certificados; no empieces sospechando del modelo.

6. Cortes de streaming y «la respuesta se detiene a mitad»

Chatbox usa salida en streaming de forma predeterminada. Las paradas a mitad suelen deberse a tres causas: un proxy o gateway que almacena en búfer el flujo SSE, un tiempo de espera por inactividad o una desconexión del upstream durante la generación. El síntoma es que la primera parte llega bien y la segunda termina de golpe, o que la interfaz se queda en «escribiendo».

Para diagnosticar, desactiva primero la salida en streaming si tu versión ofrece esa opción y compara con la misma pregunta. Si sin streaming la respuesta llega completa, el problema está en la cadena SSE; revisa entonces el búfer del proxy, los tiempos de espera y la estabilidad de la red. Las respuestas largas, los modelos de razonamiento y las horas de mayor carga lo activan con más facilidad; acorta la salida o reintenta en otro momento.

Además, un modelo de razonamiento puede «pensar» durante un tiempo prolongado antes de mostrar el texto y parecer bloqueado. Espera primero y después confirma con una solicitud sin streaming si realmente no hubo respuesta.

7. Varios dispositivos, sesiones y sincronización de configuración

Las conversaciones y los ajustes de Chatbox se guardan por defecto en la máquina. Si al cambiar de computadora o de celular no ves el historial, normalmente no es un fallo de API, sino que los datos no se trasladaron. Para migrar, usa las funciones de exportación, importación o copia de seguridad del cliente; las capacidades varían entre versiones y debes guiarte por la actual.

Las versiones más recientes de Chatbox permiten importar la configuración de un proveedor de modelos en formato JSON, lo que lleva el host, la lista de modelos y las capacidades a otro dispositivo de una vez. Aun así, conviene gestionar la clave API por separado: emite una clave por dispositivo o por persona para que una filtración solo obligue a revocar una.

Si dos dispositivos se comportan de forma distinta, compara primero la versión, el proxy del sistema y la configuración del modelo, y solo después la clave. No deduzcas directamente que el dispositivo actual tiene un problema de red porque «el otro funciona».

8. Registros y evidencia: explica el problema con claridad

Las versiones de Chatbox difieren en sus accesos a registros y diagnóstico; algunas permiten exportar desde los ajustes y otras requieren los registros del sistema. Tengas o no registros integrados, conviene anotar manualmente esta información:

  • Hora del incidente, con zona horaria, y si se reproduce de forma estable.
  • Versión de Chatbox, sistema operativo y entorno de red.
  • Código HTTP y cuerpo completo de la respuesta, eliminando la clave.
  • El request id de las cabeceras de respuesta.
  • El resultado de curl para la misma solicitud y la comparación entre streaming y no streaming.

Al abrir un ticket, oculta la clave pero conserva el ID del modelo, la marca de tiempo y el código de estado. Escribir solo «no conecta» rara vez permite localizar la causa; con esta evidencia, la mayoría de los casos se orientan en una sola ronda.

9. Un orden de diagnóstico fijo

  1. Conecta directamente al gateway con curl y confirma si la clave, el host y el modelo son válidos.
  2. Si curl falla, revisa DNS, proxy, TLS, firewall y el estado del gateway.
  3. Si curl funciona pero Chatbox falla, revisa el tipo de API, la posible duplicación de /v1, el ID del modelo y el proxy del cliente.
  4. Ante 401 revisa la clave; ante 404, la ruta y el modelo; ante 429, el consumo y la concurrencia; ante un fallo de conexión, la red y los certificados.
  5. Cambia una sola variable cada vez y vuelve a probar de inmediato, registrando el resultado.

El valor de este orden es que separa los problemas del cliente de los del servidor. La mayoría de los llamados errores de Chatbox terminan atribuyéndose a un campo de configuración o a una capa de red concreta.

Si necesitas gestionar claves, consumo y modelos de forma unificada, puedes registrarte en ZSQH AI Gateway; los modelos disponibles y la facturación se consultan en la página de precios de modelos. Los precios pueden cambiar y rige la página en el momento del pedido.

Preguntas frecuentes

Chatbox muestra «Failed to fetch». ¿Es un error de clave?

No necesariamente. Ese mensaje solo indica que el cliente no recibió respuesta, y una clave incorrecta es solo una de las causas posibles. Prueba primero el mismo host con curl; si curl también falla, revisa la red, el proxy y los certificados.

¿Por qué curl funciona pero Chatbox no conecta?

Las causas habituales son el proxy del cliente, la duplicación de /v1, un tipo de API mal elegido, un certificado del sistema que no es de confianza o una forma distinta de concatenar rutas según la versión. Compara la dirección final de la solicitud punto por punto.

Si reintento un 429, ¿se recupera solo?

Si es un límite de peticiones, aplicar retroceso y reducir la concurrencia puede ayudarte a recuperar el servicio; si es falta de cuota, reintentar no lo resolverá y tendrás que revisar la facturación o cambiar de clave. Mira primero el tipo de error en el cuerpo de la respuesta.

Si falla la lista de modelos, ¿puedo agregarlos manualmente?

Sí. Algunos gateways no exponen la interfaz de lista de modelos, pero si escribes manualmente el ID correcto la conversación funciona. La condición es que el ID, el tipo de API y el host sean correctos.

¿Las conversaciones y la configuración se sincronizan solas al cambiar de dispositivo?

Las conversaciones se guardan por defecto en la máquina y no siempre se sincronizan automáticamente. Migra con exportación e importación; las versiones más recientes permiten importar la configuración JSON del proveedor, pero la clave API conviene volver a escribirla y gestionarla por separado.

Lecturas relacionadas: