Los errores de Cherry Studio parecen variados, pero se pueden separar por capas: si la identidad pasó, si la dirección y el modelo son correctos, si la petición salió, si el proveedor limitó el ritmo y si la respuesta se cortó en tránsito. Diagnosticar por capas es más eficaz que reinstalar el cliente una y otra vez.

Este artículo clasifica los errores 401, 404, 429, los fallos de conexión, los cortes de streaming y los errores de la base de conocimiento, y ofrece un orden de diagnóstico, comandos y métodos de recogida de evidencia. Los nombres de la interfaz y las entradas de registro pueden cambiar según la versión; toma como referencia la actual.

Nota: Cherry Studio es un producto de su titular y OpenAI es una marca de su titular. Este artículo solo describe tareas de diagnóstico técnico y no implica afiliación con los fabricantes; los modelos y precios se indican en la página de precios de modelos.

1. Fija primero el orden de diagnóstico

Ante un error, guarda cuatro cosas: el código de estado HTTP, el mensaje de error del cuerpo de la respuesta, la hora de la petición y el ID de petición que devuelve el gateway. Sin ellos solo puedes decir "falló una vez"; con ellos localizas la petición concreta y el proveedor.

Después sigue este orden, cambiando una sola variable a la vez:

  1. Llama directamente al gateway con curl para confirmar dirección, clave y modelo.
  2. Si curl funciona y el cliente no, revisa la configuración del cliente, el proxy y el tipo de protocolo.
  3. Si fallan ambos, revisa clave, saldo, ID del modelo y estado del gateway.
  4. Si solo fallan las respuestas largas o la base de conocimiento, revisa streaming, tiempos de espera y modelo de embeddings.
Síntoma Causa habitual Dónde mirar primero
401 (fallo de autenticación) Clave incorrecta, caducada, con espacios o de otra plataforma Que la clave y la Base URL sean del mismo servicio
404 Not Found Sobra o falta /v1 en la ruta El final de la dirección de API
model not found ID mal escrito, mayúsculas distintas o modelo no habilitado El ID y la página de precios
429 Too Many Requests Concurrencia, frecuencia o cuota agotada Cabeceras de respuesta y consumo del gateway
Tiempo de conexión agotado Proxy, DNS, firewall o certificado Proxy del sistema y red
La respuesta se detiene El proxy o un tiempo de espera corta el streaming Desactivar streaming y comparar

2. 401: clave y autenticación

Un 401 significa que el servidor no reconoce la clave. Causas frecuentes:

  • Al copiar se añadieron espacios, saltos de línea o comillas, y la cadena enviada está incompleta.
  • La clave pertenece a otra plataforma pero se escribió bajo la Base URL actual.
  • La clave fue eliminada, rotada, su proyecto está desactivado o el saldo se agotó.
  • El cliente no guardó bien el valor: parece haber texto en el campo, pero la petición va vacía.
  • Se usa un protocolo Anthropic o Gemini contra un endpoint compatible con OpenAI, y la cabecera de autenticación no coincide.

La solución es volver a pegar la clave, confirmar que no hay espacios delante ni detrás y comprobar que la Base URL y la clave son del mismo servicio. Si el cliente tiene "Comprobar" o "Probar conexión", úsalo y luego repite con curl. Si curl funciona y el cliente da 401, revisa si la clave se guardó de verdad y si el tipo de protocolo es correcto.

3. 404 y model not found

Un 404 no siempre significa que la interfaz desapareció; muchas veces es un error al componer la ruta:

  • La Base URL incluye la ruta completa del endpoint y el cliente añade otra vez /chat/completions, duplicándola.
  • Falta /v1 donde debería ir, o sobra donde no corresponde.
  • El tipo de proveedor es incorrecto: un endpoint compatible con OpenAI configurado como Anthropic o Gemini.
  • El ID del modelo no coincide con la página de precios en mayúsculas, sufijo de fecha o guiones.
  • El modelo existe, pero la clave actual no tiene permiso para usarlo.

model not found y 404 deben tratarse por separado: el primero indica que la ruta llegó pero el modelo no es correcto; el segundo puede significar que ni siquiera se encontró la ruta. Consulta primero /v1/models para ver qué modelos devuelve el gateway; si la lista no está disponible, copia el ID exacto de la página de precios de modelos, añádelo a mano y reintenta.

4. 429: límite de frecuencia, concurrencia o cuota

Un 429 tiene al menos dos significados y cada uno se trata distinto:

  • Frecuencia o concurrencia excedidas: demasiadas peticiones en poco tiempo, o varios chats y agentes abiertos a la vez.
  • Cuota o saldo insuficiente: el proyecto de la clave no tiene saldo o alcanzó el límite de presupuesto.

Mira primero el cuerpo y las cabeceras. retry-after indica cuánto conviene esperar; si el mensaje menciona quota o balance, no sigas reintentando con espera exponencial: confirma la cuota en la consola. Solo los límites puros de frecuencia admiten retroceso exponencial, y conviene añadir variación aleatoria para que todos los clientes no reintenten en el mismo segundo.

En Cherry Studio es fácil abrir varios asistentes y comparar modelos en lote y, sin darte cuenta, multiplicar la concurrencia. Para diagnosticar, deja un solo chat con un solo modelo y, cuando la petición individual funcione, ve restaurando el resto.

5. Fallos de conexión, SSL y proxy

Suelen aparecer como un indicador girando que termina en tiempo agotado, imposibilidad de conectar o error de certificado. Cherry Studio suele ofrecer tres modos de proxy: proxy del sistema, proxy personalizado y sin proxy; están en los ajustes del sistema o generales, con nombres según la versión.

Orden de diagnóstico:

  1. Confirma que el proxy del sistema o la VPN está activo y que el cliente usa el modo "proxy del sistema".
  2. Si configuraste un proxy propio, verifica dirección y puerto, por ejemplo http://127.0.0.1:7890.
  3. Revisa la lista de exclusión del proxy y confirma que el dominio de destino no está excluido por error ni forzado a pasar por el proxy.
  4. Cambia temporalmente a "sin proxy" para comparar y saber si el problema viene del enlace del proxy.
  5. Si la red corporativa intercepta TLS, comprueba que el certificado del sistema y la cadena de confianza del cliente están completos.
  6. Revisa la hora del sistema: una desviación grande hace fallar la validación del certificado.

Un error común es escribir la dirección del proxy en la dirección de API. La dirección de API debe ser la HTTPS del gateway, y el proxy se configura en los ajustes de proxy; no mezcles ambos.

6. Cortes en la salida en streaming

La respuesta en streaming depende de una conexión larga. El síntoma típico es que aparecen las primeras palabras y luego se detiene a los segundos o decenas de segundos, o solo se muestra una parte. Las causas incluyen almacenamiento en búfer del proxy, tiempo de espera por inactividad, tiempo de espera del gateway y cambios de red.

Para diagnosticar, desactiva primero el streaming y repite la misma pregunta. Si la respuesta sin streaming funciona, el problema está casi seguro en el enlace de transporte: revisa el software de proxy, el firewall y los tiempos de espera del proxy inverso. Este último debe desactivar el búfer de respuesta y ampliar el tiempo de lectura; de lo contrario, SSE se acumula y llega de golpe o se corta a mitad.

También conviene distinguir "el modelo se detuvo" de "la conexión se cortó". Lo primero suele traer una marca de fin; lo segundo no siempre deja código de error, solo texto incompleto. Registra ambos casos por separado para saber después si el problema es del cliente, del gateway o de la red.

7. Errores de la base de conocimiento y de embeddings

Los errores de la base suelen estar en los embeddings o en la recuperación, no en la interfaz de chat:

  • Solo hay modelo de chat, sin un modelo de embeddings disponible.
  • El modelo de embeddings no admite la interfaz actual o devuelve una dimensión distinta a la del índice.
  • El archivo no se puede analizar, por ejemplo un PDF escaneado sin texto extraíble.
  • Se cambió el modelo de embeddings sin reconstruir el índice, y los vectores antiguos no coinciden con la consulta nueva.
  • El servicio de reranking o recuperación no responde, y la búsqueda sale vacía o tarda demasiado.

La base de conocimiento de Cherry Studio puede usar recuperación por palabras clave o añadir embeddings para una búsqueda híbrida; al cambiar de modelo, la interfaz activa una reconstrucción. Confirma antes que el modelo nuevo responde y no cambies a la vez los parámetros de fragmentación, o no podrás saber qué causó la diferencia. La entrada exacta depende de la documentación de tu versión.

8. Registros, comandos de diagnóstico y evidencia

Cherry Studio tiene un modo de desarrollador que se activa en Ajustes y muestra la cadena de llamadas para localizar errores de modelos y herramientas; la entrada varía según la versión. Del lado del gateway conviene conservar ID de petición, nombre del modelo, duración y tokens consumidos; si las marcas de tiempo de ambos lados coinciden, es más fácil saber en qué tramo falló.

Primero reproduce el problema mínimo con curl:

export ZSQH_API_KEY="sk-tu-clave"

# 1. Comprobar si la dirección y la clave son válidas
curl -sS "https://ai.zhongshangqihang.com/v1/models" \
  -H "Authorization: Bearer $ZSQH_API_KEY" \
  -w "\nHTTP %{http_code}\n"

# 2. Comprobar si el modelo se puede llamar
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"

# 3. Revisar aparte el handshake TLS y la cadena de certificados
openssl s_client -connect ai.zhongshangqihang.com:443 -servername ai.zhongshangqihang.com </dev/null

Los tres comandos corresponden a tres preguntas: clave y dirección, modelo y parámetros, TLS y certificados. Donde falle un paso, sigue por esa capa; no cambies a la vez clave, dirección y modelo.

Preguntas frecuentes

¿Basta con cambiar la clave cuando da 401?

No siempre. Cambiarla descarta un problema de clave, pero si la Base URL y la clave son de plataformas distintas, el protocolo está mal elegido o el cliente no guardó la clave, cambiar muchas veces no sirve. Confirma primero a dónde llegó realmente la petición.

¿Un 404 significa que el modelo se retiró?

En la mayoría de los casos la ruta de la Base URL es incorrecta o el ID está mal escrito. Pide /v1/models con curl y contrasta el identificador en precios de modelos; si ambos pasos están bien, entonces considera si el modelo fue retirado.

¿Un 429 obliga siempre a bajar la concurrencia?

No. Lee primero el mensaje: solo un límite puro de frecuencia requiere bajar concurrencia y esperar; si falta cuota, reducir la velocidad no sirve, hay que revisar el saldo o el presupuesto en la consola. La cabecera retry-after ayuda a calcular la espera.

¿Por qué solo se cortan las respuestas en streaming?

El streaming depende de conexiones largas y es más vulnerable al búfer del proxy, al tiempo de espera por inactividad del firewall o al tiempo de espera del proxy inverso. Desactívalo para comparar; si sin streaming funciona, revisa primero proxy y tiempos de espera en lugar de reinstalar el cliente.

¿Los errores de la base de conocimiento se diagnostican aparte?

Sí. El chat usa la interfaz de conversación; la base de conocimiento implica además análisis de archivos, modelo de embeddings, índice vectorial y servicio de recuperación. Confirma que el modelo de chat funciona y después revisa si el de embeddings responde, si la dimensión coincide y si hace falta reconstruir el índice.

Próximos pasos

El orden se resume en una frase: primero curl, después el cliente; primero el código de estado, después los registros; una sola variable a la vez. Si necesitas un punto de entrada compatible con OpenAI, registros de peticiones y gestión de consumo, puedes registrarte en ZSQH AI Gateway; los modelos y precios se indican en la página de precios de modelos.

Lecturas relacionadas: