Resolución de problemas con las URLs base de OpenAI
Cambiar de modelo debería ser fácil. Cambias el endpoint y mantienes el SDK.
En proyectos reales, la primera ejecución suele fallar. Verás errores como 401, 404 o 429.
Usa esta lista de verificación antes de culpar al SDK.
Comprueba el prefijo /v1 La mayoría de las pasarelas (gateways) necesitan el sufijo /v1 en la URL. Si usas solo el dominio, es posible que el SDK llame a la ruta incorrecta. Copia el formato exacto de la documentación del proveedor.
Verifica tus claves API Mezclar claves provoca fallos. Revisa estos errores comunes: • Usar una clave de OpenAI con una URL de relay. • Usar una clave de relay con una URL de OpenAI. • Usar una clave de un proyecto desactivado. • Incluir un espacio al principio o al final de la clave. Si ves un error 401, imprime el primer y el último carácter de tu clave para compararla con tu panel de control (dashboard). No registres la clave completa.
Coincide exactamente con los nombres de los modelos No adivines los nombres de los modelos. Los nombres de las pasarelas cambian. Un nombre incorrecto provoca errores 404 o
model_not_found. Copia el ID del modelo directamente de la lista de modelos actual.Ejecuta primero una petición mínima Antes de depurar toda tu aplicación, realiza una pequeña prueba. Usa un mensaje de "ping" sencillo y un valor bajo de
max_tokens. Si esto funciona, tu URL, clave y modelo están bien. El error reside en la lógica de tu aplicación, como en el streaming o la llamada a herramientas (tool calling).Comprende los códigos de error • 401 significa un problema de clave o de cuenta. • 429 significa un problema de límite de tasa (rate limit) o de saldo. Si ves un 429, revisa tu página de facturación. Evita los bucles de reintento intensos. Solo empeoran el problema.
Consulta la página de estado Si tu código funcionaba ayer pero falla hoy, no reescribas tu integración. Consulta primero la página de estado del proveedor. A menudo, la causa es un incidente en el servicio de origen (upstream).
Usa un comando curl Mantén un comando curl sencillo en la documentación de tu proyecto.
Cuando tu aplicación falle, ejecuta primero el comando curl. Si curl falla, el problema es la cuenta, la pasarela o la red. Si curl funciona, el problema es el código de tu aplicación.