Nota del autor: si curl funciona, pero el cliente devuelve un error 401, 404 o 400, o no logra conectarse, revisa en orden estos 7 puntos del servicio proxy de API. Incluye una tabla de códigos de error y una lista de comprobación de 10 minutos.
Con la misma clave y el mismo modelo, una solicitud con curl devuelve 200, pero al configurar Cherry Studio, Chatbox, Cursor, Cline, Claude Code o Codex CLI aparece un error 401, 404 o 400, o simplemente se agota el tiempo de espera o llega una respuesta vacía. En ese caso, revisa primero la configuración del cliente; no cambies la clave de inmediato. Si curl funciona, ya sabes que la clave es válida y que hay acceso a la red. Lo más probable es que la solicitud que envía el cliente sea distinta de lo que crees.
El orden recomendado es: URL base → protocolo y endpoint → encabezado de autenticación → ID del modelo → cuerpo de la solicitud → red. Antes de empezar, comprueba también si el cliente ha leído los cambios de configuración. En este artículo dividimos el recorrido de la solicitud en 7 puntos de control. Para cada uno veremos el síntoma, la causa, cómo verificarlo y cómo solucionarlo. El objetivo es que puedas determinar en 10 minutos si el problema está en el cliente, la pasarela o el proveedor.
Este no es otro artículo sobre los fundamentos de las API, sino una guía de solución de problemas que puedes seguir paso a paso.
Por qué curl funciona, pero el cliente no se conecta: claves para diagnosticar un servicio proxy de API
curl solo comprueba una parte de la cadena: la resolución DNS, el intercambio TLS, la conectividad de red, la validez de la clave y la disponibilidad del endpoint al que has enviado la solicitud manualmente. No comprueba si el cliente ha leído la configuración que modificaste, cómo construye la Base URL ni si las cabeceras y el cuerpo de su solicitud coinciden con los de curl.
Una solicitud del cliente suele recorrer esta cadena: configuración del cliente (variables de entorno, archivo de configuración, interfaz gráfica) → construcción de la Base URL → protocolo y endpoint → cabecera de autenticación → ID y mapeo del modelo → cuerpo de la solicitud (mensajes, herramientas, contenido multimodal, streaming) → proxy, TLS y red → gateway → modelo de origen. Que curl funcione solo demuestra que la ruta que escribiste manualmente funciona. El cliente podría estar siguiendo una completamente distinta.
| Punto de comprobación | Síntoma habitual | Qué comprobar primero |
|---|---|---|
| 1. Lectura de la configuración | Los cambios no surten efecto y aparece el mismo error de antes | Revisar la URL real de la solicitud en los logs del cliente |
| 2. Construcción de la Base URL | Error 404; aparece /v1/v1 o // en la ruta |
Comparar la URL del log con la de curl |
| 3. Protocolo y endpoint | Error 404 o 400, o fallo al interpretar el formato de la respuesta | Confirmar qué protocolo utiliza el cliente |
| 4. Cabecera de autenticación | Error 401, aunque la clave funciona en curl | Comparar las cabeceras de las solicitudes |
| 5. ID del modelo | Error 404 o 400 que indica que el modelo no existe | Compararlo carácter por carácter con la lista de modelos del gateway |
| 6. Cuerpo de la solicitud | El texto funciona, pero al añadir imágenes o herramientas aparece un error 400 | Añadir variables gradualmente para reproducir el fallo |
| 7. Red y streaming | Tiempo de espera agotado, stream disconnected o respuesta vacía | Desactivar el streaming para comparar y revisar el proxy |
Puntos de diagnóstico del servicio proxy de API 1-2: lectura de la configuración y construcción de la Base URL
Punto 1: ¿El cliente está leyendo la configuración que modificaste?
Síntoma: ya cambiaste la Base URL y la clave API, pero el error es exactamente el mismo; o funciona en un proyecto, pero no en otro.
Causa: la mayoría de los clientes obtienen su configuración de más de una fuente. Por ejemplo, los ajustes de la interfaz gráfica pueden sobrescribir las variables de entorno; el archivo de configuración puede tener varios perfiles y el activo no ser el que modificaste; la configuración del proyecto puede sobrescribir la global; o un proceso antiguo puede seguir usando los valores que cargó al iniciarse. Esto último es especialmente común con las herramientas de línea de comandos: cambias una variable de entorno en la terminal, pero un IDE o proceso de agente que ya está en ejecución no recibe el cambio.
Cómo comprobarlo: abre los registros del cliente o la salida de depuración y comprueba si la URL de la solicitud y los primeros caracteres de la clave coinciden con los valores que acabas de configurar. Si no puedes consultar los registros fácilmente, cambia la Base URL por una dirección claramente incorrecta y observa si cambia el error. Así podrás saber si la configuración está surtiendo efecto.
Cómo solucionarlo: primero, averigua el orden de prioridad de la configuración del cliente. Normalmente, los ajustes de la interfaz gráfica o del proyecto tienen prioridad sobre el archivo de configuración global, y este sobre las variables de entorno. Las reglas varían según el cliente, así que consulta su documentación. Después, modifica solo la fuente con mayor prioridad, elimina los valores conflictivos de las demás y cierra por completo el proceso del cliente antes de reiniciarlo.
Punto 2: barra final, duplicación de /v1 y prefijos de ruta en la Base URL
Síntoma: recibes un error 404 y la URL de los registros contiene /v1/v1/chat/completions, //chat/completions o termina convertida en /v1/chat/completions/chat/completions.
Causa: cada cliente puede interpretar de forma distinta el campo Base URL. Algunos esperan la dirección raíz y añaden /v1 automáticamente; otros esperan una dirección que termine en /v1 y después añaden /chat/completions; y otros separan la Base URL y el endpoint completo en dos campos. Si introduces https://api.apiyi.com/v1/chat/completions completo en un campo que solo acepta el prefijo, o añades una barra al final de una dirección que ya contiene /v1, la ruta resultante puede ser incorrecta.
Cómo comprobarlo: compara carácter por carácter la URL completa de la solicitud en los registros con la que usas en curl. Fíjate especialmente en cuántas veces aparece /v1, si hay barras dobles y si sobra algún segmento al final de la ruta.
Cómo solucionarlo: rellena el campo según la documentación del cliente. En los clientes compatibles con OpenAI, normalmente se usa https://api.apiyi.com/v1, sin barra al final. Si el cliente añade /v1 automáticamente, elimina el /v1 que escribiste. Después del cambio, revisa de nuevo la URL en los registros y confirma que la ruta final tenga una forma estándar como https://api.apiyi.com/v1/chat/completions.
🎯 Recomendación de configuración: la dirección de acceso compatible con OpenAI de APIYI (apiyi.com) es
https://api.apiyi.com/v1y se configura igual que en el SDK oficial de OpenAI. Puedes consultar los modelos disponibles en la consola o solicitar la lista de modelos usando la misma Base URL. Úsala primero para comprobar que la clave API y la dirección son correctas antes de configurar el cliente.
Puntos de diagnóstico 3-4 del servicio proxy de API: protocolo, endpoint y encabezados de autenticación
Punto 3: ¿Coinciden el protocolo y el endpoint?
Síntoma: La URL base parece correcta, pero sigues recibiendo un error 404 o 400. También puede que la solicitud se complete, pero el cliente indique que «no se puede interpretar la respuesta» o devuelva contenido vacío.
Causa: Las interfaces actuales de los Modelos de Lenguaje Grande utilizan más de un protocolo. Puede que el cliente solo admita Chat Completions y lo hayas dirigido a un endpoint que solo ofrece Responses. Claude Code utiliza el protocolo Anthropic Messages, no OpenAI Chat Completions. El formato nativo de Gemini y el formato compatible con OpenAI también tienen rutas y cuerpos de solicitud completamente distintos. En curl puedes escribir el endpoint correcto a mano, mientras que el cliente podría hacer la solicitud según su propio protocolo predeterminado.
| Tipo de protocolo | Ruta típica del endpoint | Usuarios habituales | Método de autenticación |
|---|---|---|---|
| OpenAI Chat Completions | /v1/chat/completions |
Muchos clientes, como Cherry Studio, Chatbox y Cline | Authorization: Bearer |
| OpenAI Responses | /v1/responses |
Herramientas recientes del ecosistema OpenAI | Authorization: Bearer |
| Anthropic Messages | /v1/messages |
Herramientas nativas de Anthropic, como Claude Code | x-api-key y anthropic-version |
| Gemini nativo | Interfaz nativa cuya ruta incluye el nombre del modelo | SDK nativo de Gemini | Consulta la documentación oficial y la del gateway |
Cómo comprobarlo: Revisa el último segmento de la ruta de solicitud en los registros del cliente para identificar el protocolo que utiliza. Después, confirma que el endpoint del gateway que elegiste lo admita. Si el cliente tiene un menú desplegable para «tipo de proveedor» o «formato de API», verifica que la opción coincida con el protocolo que quieres usar.
Cómo solucionarlo: Asegúrate de que el tipo de protocolo, la URL base y el modelo del cliente sean compatibles entre sí. Para usar el formato compatible con OpenAI, selecciona un proveedor de tipo OpenAI; para herramientas nativas como Claude Code, configura el protocolo Anthropic; y, si necesitas funciones nativas de Gemini, usa el formato de Gemini. APIYI admite tanto el formato compatible con OpenAI como los formatos de API nativos de Claude, Gemini y otros. Consulta la documentación de docs.apiyi.com para conocer las direcciones de conexión de cada formato nativo; no construyas las rutas de memoria.
Punto 4: ¿Coinciden los encabezados de autenticación con el protocolo?
Síntoma: Aparece un error 401, pero la misma clave funciona perfectamente en curl.
Causa: Las interfaces compatibles con OpenAI suelen usar Authorization: Bearer <Key>; las interfaces nativas de Anthropic suelen usar x-api-key junto con anthropic-version; y algunas plataformas también requieren encabezados relacionados con la organización o el proyecto. Puede que en curl hayas escrito los encabezados correctos, pero que el cliente envíe otros según un protocolo diferente, o incluya un encabezado de organización que el gateway no reconoce, lo que provoca el fallo de autenticación.
Cómo comprobarlo: Compara los encabezados de curl con los de los registros del cliente, especialmente los campos Authorization, x-api-key, Content-Type y OpenAI-Beta. Comprueba también que no haya espacios, saltos de línea ni comillas de más antes o después de la clave; es algo habitual al copiar y pegar desde una página web.
Cómo solucionarlo: Los encabezados de autenticación dependen del protocolo. Si eliges el correcto, la mayoría de los clientes enviarán automáticamente los encabezados adecuados. Si el cliente permite personalizarlos, elimina los encabezados de organización o proyecto que no sean necesarios. Vuelve a pegar la clave y asegúrate de que no tenga caracteres adicionales.
Diagnóstico del servicio proxy de API, puntos 5-7: ID del modelo, cuerpo de la solicitud y streaming de red
Punto de comprobación 5: ID y mapeo del modelo
Síntoma: aparece un error 404 o 400 que indica que el modelo no existe o no es válido; también puede ocurrir que solo falle un modelo y los demás funcionen correctamente.
Causa: el ID del modelo debe coincidir carácter por carácter con el de la lista de modelos del gateway. Las diferencias más comunes incluyen mayúsculas y minúsculas, sufijos de versión, prefijos (por ejemplo, el formato provider/model) y alias. Un mismo modelo puede tener nombres distintos según la plataforma. Además, es posible que la lista integrada del cliente ni siquiera incluya el ID que buscas y lo sustituya silenciosamente por el valor predeterminado.
Cómo comprobarlo: copia el ID del modelo desde la interfaz de lista de modelos del gateway o desde la consola y compáralo carácter por carácter con el campo model del cuerpo de la solicitud en los registros del cliente. Si solo falla un modelo, comprueba primero que el ID y el endpoint coincidan y, después, que la cuenta tenga acceso a ese modelo.
Cómo solucionarlo: añade manualmente un modelo personalizado en el cliente y pega directamente el ID proporcionado por el gateway, sin escribirlo a mano. Si el cliente aplica un mapeo de modelos, comprueba que el nombre resultante sea correcto.
💡 Recomendación sobre los ID de modelo: si usas una sola clave en APIYI apiyi.com para invocar modelos de OpenAI, Claude, Gemini, DeepSeek, Qwen y otros proveedores, toma como referencia los ID de la lista de modelos de la consola. Un mismo modelo puede tener nombres distintos según la plataforma, así que copiarlo desde la consola es la forma más sencilla de evitar errores. Consulta también la consola y la documentación para comprobar la disponibilidad de los modelos.
Punto de control 6: cuerpo de la solicitud y formato multimodal
Síntoma: la conversación de texto funciona, pero aparece un error 400 al enviar una imagen, invocar una herramienta o activar parámetros de razonamiento.
Causa: los problemas de compatibilidad en el cuerpo de la solicitud suelen aparecer en estos puntos: la estructura del array content multimodal; la forma de escribir el campo image_url; imágenes en base64 sin un prefijo MIME como data:image/png;base64,; campos de invocación de herramientas que no cumplen el protocolo actual; requisitos distintos para max_tokens y max_completion_tokens según el modelo; y parámetros relacionados con reasoning que solo aceptan algunos modelos. Los parámetros no son completamente intercambiables entre proveedores.
Cómo verificarlo: añade variables paso a paso. Primero envía texto sin formato; si funciona, activa el streaming, después añade la invocación de herramientas y, por último, el contenido multimodal. Haz una prueba cada vez que añadas una variable: el campo problemático estará en el paso donde empiece a fallar. El mensaje de error suele señalar el campo concreto, así que revisa la respuesta de error completa.
Cómo solucionarlo: desactiva los parámetros avanzados que no necesites en el cliente y ajusta los campos según la documentación del modelo elegido. Para las imágenes, usa un prefijo base64 válido o una URL accesible; para las herramientas, escribe las definiciones con el formato del protocolo actual.
Punto de control 7: red, proxy, TLS y almacenamiento en búfer del streaming
Síntoma: la conexión agota el tiempo de espera, aparece stream disconnected, llega una respuesta vacía tras una larga espera o las solicitudes sin streaming funcionan, pero las que usan streaming fallan.
Causa: puede que el cliente use el proxy del sistema o el definido en las variables de entorno y curl no, o viceversa. Los firewalls corporativos, la validación de certificados TLS, la resolución de IPv6 y el DNS también pueden impedir que el cliente se conecte. En solicitudes con streaming, algunos proxies almacenan la respuesta en búfer y no la reenvían hasta que reciben todo el contenido. Si el cliente no recibe datos mientras tanto, puede agotar el tiempo de espera o dar la transmisión por interrumpida.
Cómo verificarlo: primero distingue entre «no se estableció la conexión» y «la transmisión se interrumpió». En el primer caso, busca errores de TLS o de conexión; en el segundo, normalmente ya habrás recibido parte del contenido. Desactiva el streaming y vuelve a probar. Si la solicitud funciona sin streaming, lo más probable es que el problema esté en el almacenamiento en búfer del proxy o en la configuración del tiempo de espera. Comprueba que las variables de entorno del proxy coincidan entre el cliente y la terminal.
Cómo solucionarlo: unifica la configuración del proxy del cliente y de curl; evita usar proxies que almacenen respuestas en búfer para solicitudes con streaming; y aumenta el tiempo de espera del cliente si es necesario. Si el servicio de origen sufre interrupciones ocasionales, puedes hacer un número limitado de reintentos o cambiar temporalmente a otro modelo para comprobar si el problema afecta a un solo servicio de origen.
Guía rápida del servicio proxy de API: códigos de error y lista de verificación del cliente
Cuando aparezca un error, usa el código para acotar las posibles causas y después revisa la configuración punto por punto.
Tabla de códigos de error
| Código de error | Causas habituales | Qué revisar primero |
|---|---|---|
| 401 | Clave API inválida, caducada o deshabilitada; formato incorrecto de la cabecera; organización o proyecto incorrectos | Puntos 1 y 4 |
| 403 | La clave API es válida, pero una política del modelo, la organización o la región la rechaza; lista blanca de IP; modelo no habilitado | Punto 5 y permisos de la cuenta |
| 404 | Ruta incorrecta en la URL base; el endpoint o el ID del modelo no existen; la puerta de enlace no implementa esa ruta | Puntos 2, 3 y 5 |
| 400 | Cuerpo de la solicitud, parámetros, ID del modelo o campos multimodales no válidos; parámetros incompatibles con el proveedor | Puntos 5 y 6 |
| 429 | Límite de solicitudes o cuota insuficiente | Revisa Retry-After, espera antes de reintentar o cambia de modelo |
| 500/502/503/529 | Error del servicio de origen o de la puerta de enlace; 529 suele indicar sobrecarga | Haz un número limitado de reintentos y revisa los registros de la puerta de enlace |
| Tiempo de espera agotado, stream disconnected | Interrupción de la red, el proxy, TLS o el servicio de origen | Punto 7 |
Lista de verificación de la configuración del cliente
| Elemento | Qué debes comprobar |
|---|---|
| Origen de la configuración | ¿Modificaste variables de entorno, un archivo de configuración o la interfaz gráfica? ¿Cuál tiene mayor prioridad? ¿Hay varios perfiles o configuraciones de proyecto que se sobrescriban entre sí? |
| URL base | ¿Incluye /v1? ¿El cliente añade /v1 automáticamente? ¿Hay una barra adicional al final? |
| Tipo de endpoint | ¿Chat Completions, Responses o la API nativa de Claude o Gemini? ¿Lo admite la versión del cliente? |
| Cabecera de autenticación | ¿Usa Authorization: Bearer o x-api-key? ¿Necesita anthropic-version? |
| ID del modelo | ¿Coincide exactamente con la lista de modelos de la puerta de enlace, incluidas las mayúsculas, minúsculas y los prefijos? |
| Cuerpo de la solicitud | ¿Incluye herramientas, imágenes o parámetros de razonamiento? ¿El campo max_tokens es compatible con el modelo de destino? |
| Streaming y red | ¿Está activado el streaming? ¿El proxy almacena la respuesta en búfer? ¿La configuración del proxy es la misma en el cliente y en curl? |
Reproduce el problema con una solicitud mínima
El método más eficaz es hacer una comparación con las mismas variables: usa la misma URL base, clave API, modelo y cuerpo de solicitud; envía la solicitud primero con curl y luego con el cliente. Sigue estos pasos:
- Verifica la clave API y la URL base con el endpoint de listado de modelos, por ejemplo, enviando una solicitud a
https://api.apiyi.com/v1/models; - Verifica el endpoint y el ID del modelo con una solicitud de chat mínima de texto sin formato;
- Activa el streaming para verificar la red y el proxy;
- Añade invocaciones de herramientas o contenido multimodal para verificar el cuerpo de la solicitud;
- En cada paso, revisa tanto los registros del cliente como los de la puerta de enlace.
🚀 Consejo para resolver problemas: La consola de APIYI permite consultar estadísticas de uso y registros detallados de las invocaciones. Si el cliente muestra un error, pero no hay ningún registro de esa invocación en la consola, la solicitud no llegó a la puerta de enlace y el problema está en la configuración del cliente o en la red local. Si hay un registro con información del error, puedes usarlo para determinar si el problema está en los parámetros o en el servicio de origen.
Preguntas frecuentes (FAQ)
Q1: Si curl funciona pero el cliente no se conecta, ¿sirve cambiar la clave API?
Por lo general, no. Si curl funciona, ya sabes que la clave API es válida. Cuando parece que «cambiar la clave lo solucionó», a menudo es porque al hacerlo también se reinició el cliente o se cambió de perfil, lo que recargó la configuración. En lugar de cambiar la clave, cierra el cliente por completo, reinícialo y comprueba en los registros qué Base URL y clave API está usando realmente. También puedes revisar el estado de la clave y su historial de llamadas en la consola de APIYI para confirmar si hay algún problema con ella.
Q2: ¿Por qué funciona el endpoint /models, pero falla la solicitud de chat?
El endpoint de lista de modelos solo confirma que la autenticación y la Base URL son básicamente correctas; no comprueba el endpoint de chat, el ID del modelo ni el cuerpo de la solicitud. Si el chat falla, revisa en este orden: si el protocolo que usa el cliente coincide con el endpoint (punto de comprobación 3), si el ID del modelo coincide exactamente con el de la lista (punto de comprobación 5) y si el cuerpo de la solicitud incluye parámetros que el modelo de destino no admite (punto de comprobación 6).
Q4: Si solo falla un modelo y los demás funcionan, ¿qué debo revisar primero?
Primero revisa el ID del modelo y el endpoint; después, los permisos de la cuenta. Lo más habitual son las diferencias en mayúsculas, minúsculas, prefijos o alias del ID. Otra posibilidad es que el modelo requiera un protocolo diferente, como su formato nativo. Por último, comprueba los permisos o la disponibilidad. Con una sola clave de APIYI puedes cambiar entre modelos de distintos proveedores. Prueba temporalmente otro modelo similar para determinar rápidamente si el problema afecta a un solo modelo o a la configuración general.
Q5: ¿Cómo puedo saber si el problema está en el cliente o en la puerta de enlace?
Fíjate en dos cosas: si la puerta de enlace recibió la solicitud y si la misma solicitud funciona al enviarla con curl. Si no hay ningún registro en la puerta de enlace, lo más probable es que el problema esté en el cliente o en la red local. Si la misma solicitud funciona con curl pero falla en el cliente, probablemente el problema esté en cómo el cliente construye la solicitud o en su cuerpo. Si también falla con curl y los registros muestran un error 5xx, es momento de contactar con el soporte de la puerta de enlace.
Resumen: lista de verificación de 10 minutos para el servicio proxy de API y cuándo pedir ayuda
Si «curl funciona, pero el cliente no se conecta», no te apresures a cambiar la clave. Repasa esta lista en 10 minutos:
- Revisa los registros del cliente: obtén la URL, las cabeceras y el cuerpo de la solicitud real, y confirma que la configuración se haya aplicado;
- Comprueba la Base URL: asegúrate de que
/v1aparezca una sola vez y de que no haya barras dobles ni segmentos de ruta repetidos; - Comprueba el protocolo del endpoint: Chat Completions, Responses, Claude Messages o el formato nativo de Gemini debe coincidir con el tipo de cliente;
- Comprueba la cabecera de autenticación:
Authorization: Bearerox-api-key; elimina las cabeceras de organización innecesarias y los espacios al principio o al final de la clave; - Comprueba el ID del modelo: compáralo carácter por carácter con la lista de modelos de la puerta de enlace;
- Envía una solicitud mínima: usa la misma clave, el mismo modelo y el mismo cuerpo para enviar una solicitud con curl y otra con el cliente, y compara los resultados;
- Activa el streaming: si falla, revisa el almacenamiento en búfer y los tiempos de espera del proxy;
- Añade herramientas o contenido multimodal: si falla, revisa los campos del cuerpo de la solicitud;
- Determina el origen: usa los registros de la puerta de enlace para decidir si el problema está en el cliente o en la puerta de enlace.
Cuándo se trata de un bug del cliente: no hay ningún registro de la llamada en la puerta de enlace, o curl funciona con exactamente la misma URL, cabeceras y cuerpo, pero el cliente falla, y ya has confirmado que la configuración es correcta y que la versión es compatible con el endpoint. En ese caso, actualiza el cliente o informa del problema al proyecto correspondiente.
Cuándo contactar con el soporte de la puerta de enlace: la misma solicitud mínima también falla con curl, los registros de la puerta de enlace muestran la llamada y una respuesta 5xx; o bien, un modelo sigue dando errores mientras que otros funcionan, después de haber descartado problemas con el ID del modelo y los permisos. Al contactar con soporte, incluye la hora de la solicitud, el ID del modelo, el código de error y el mensaje de error de los registros para agilizar el diagnóstico.
Para las herramientas de equipo que necesitan estabilidad, disponer de varios modelos y rutas es en sí una forma de diagnosticar problemas: si falla uno, puedes cambiar a otro y comparar los resultados para identificar enseguida el alcance del problema. APIYI apiyi.com permite acceder con una sola clave al formato compatible con OpenAI y a los formatos nativos de Claude y Gemini, y validar rápidamente las llamadas mediante los datos de uso y los registros de la consola. Consulta la consola y la documentación para conocer los precios y la disponibilidad.
Autor: equipo técnico de APIYI
Consultas técnicas: contáctanos desde la página de inicio de APIYI
