Solución de problemas de APIs compatibles con OpenAI: corrige 401, nombres de modelo, streaming y URLs base

La resolución de problemas de una API compatible con OpenAI se vuelve mucho más fácil cuando dejas de tratar cada solicitud fallida como si fuera "el proveedor está caído". La mayoría de las migraciones fallidas provienen de una de seis capas: la clave, la URL base, la familia de endpoints, el nombre del modelo, el comportamiento de streaming o la facturación/lectura.

Flatkey ayuda a los equipos a mantener el acceso a modelos, el enrutamiento, la facturación, el análisis de uso y los controles operativos en un solo lugar, pero un cliente compatible con OpenAI aún necesita una configuración precisa. Una solicitud puede parecer correcta en el SDK y aun así fallar porque el cliente apunta a la raíz /v1 equivocada, el alias del modelo pertenece a una familia de endpoints diferente, o el stream está siendo almacenado en búfer por un proxy.

Usa esta guía de resolución de problemas de API compatible con OpenAI como un camino de depuración limpio antes de cambiar el código de la aplicación. Empieza con curl, verifica una solicitud no streaming, agrega el SDK y luego añade streaming, herramientas y tráfico de producción, una capa a la vez.

El camino de resolución de problemas de la API compatible con OpenAI en cinco minutos

Antes de inspeccionar el código del framework, captura la solicitud más pequeña que debería funcionar. Para Flatkey, usa la URL base que se muestra en tu consola actual. La página principal pública de Flatkey muestra actualmente una solicitud a https://router.flatkey.ai/v1/chat/completions, lo que significa que los clientes del SDK normalmente deberían recibir la raíz /v1 como URL base y el SDK debería añadir /chat/completions.

export FLATKEY_API_KEY="sk-fk-..."
export FLATKEY_BASE_URL="https://router.flatkey.ai/v1"
export FLATKEY_MODEL="your-model-alias"

curl -sS "$FLATKEY_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$FLATKEY_MODEL"'",
    "messages": [
      {"role": "user", "content": "Responde exactamente: ok"}
    ]
  }'

Si esta solicitud falla, el problema no es el framework de tu app. Primero corrige la clave, la URL base, la familia de endpoints o el alias del modelo. Si funciona, copia los mismos valores al SDK y sigue depurando desde ahí.

La regla más rápida para la resolución de problemas de una API compatible con OpenAI es simple: no pruebes streaming, herramientas, modo JSON, reintentos ni un flujo completo de agente hasta que una solicitud de texto simple sin streaming funcione.

Lee el error como una capa, no como un veredicto

Usa el código de estado para decidir qué cambiar después.

Síntoma	Capa probable	Qué comprobar primero
401, invalid_api_key o error de autenticación	Clave y encabezado de autenticación	Formato Bearer, origen de la clave, espacios en blanco copiados, clave del proveedor versus clave del gateway
403 o acceso denegado	Cuenta, proyecto o política	Lista de अनुमति/allowlist de IP, pertenencia al proyecto, aprobación del modelo, permiso del endpoint
404, model_not_found o modelo desconocido	Catálogo de modelos y familia de endpoints	Alias exacto del modelo, estado de habilitación del modelo, /chat/completions frente a /responses frente a otro endpoint
Solicitud 400 mal formada	Forma del payload	Campos obligatorios, parámetros no compatibles, esquema de herramientas, formato de mensaje
La conexión de stream se abre pero no aparecen tokens	Ruta de streaming	stream: true, analizador SSE, proxy con buffering, compatibilidad de stream del endpoint
La solicitud se completa pero falta el uso	Lectura y facturación	Solicitud de comparación sin streaming, registro en el panel, comportamiento del evento final del stream
429, 500, 502, 503 o 504	Tasa, capacidad o upstream	Backoff, volumen de solicitudes, página de estado, política de reintentos, ruta de fallback

La propia guía de errores de OpenAI trata los 401 como problemas de autenticación, los 429 como problemas de tasa o cuota, y las respuestas 500/503 como condiciones reintentables del servidor o de sobrecarga. Un gateway compatible con OpenAI puede añadir sus propios detalles, así que conserva el cuerpo de la respuesta y el ID de la solicitud cuando escales el problema.

Corrige los 401 antes de cambiar de modelo

Un 401 es el desvío más común en la resolución de problemas de una API compatible con OpenAI porque parece un problema de modelo o de ruta cuando normalmente es un problema de autenticación.

Comprueba esto en orden:

1. La solicitud tiene exactamente un encabezado Authorization: Bearer ....
2. La clave es una clave de Flatkey cuando llamas a Flatkey, no una clave directa de OpenAI, Anthropic, Google o de prueba.
3. La clave no tiene comillas copiadas, saltos de línea, prefijos invisibles ni espacios finales.
4. La clave se carga desde el entorno en el que realmente se ejecuta tu proceso, no solo desde tu shell.
5. La cuenta, el proyecto, el equipo o la política de IP permiten la ruta.

Usa una comprobación breve en shell que no imprima la clave:

test -n "$FLATKEY_API_KEY" && echo "la clave está configurada"
printf '%s' "$FLATKEY_API_KEY" | wc -c

Si curl funciona pero el SDK devuelve 401, inspecciona los nombres de las variables de entorno. El cliente de Python de OpenAI lee OPENAI_API_KEY por defecto, y el cliente de Node lee OPENAI_API_KEY por defecto. Si tu app todavía exporta OPENAI_API_KEY con una clave antigua del proveedor directo, el SDK puede ignorar tu nueva clave del gateway a menos que pases api_key o apiKey explícitamente.

Corrige la URL base sin duplicar el endpoint

Los errores de URL base normalmente caen en dos patrones:

1. El SDK recibe el endpoint completo, como https://router.flatkey.ai/v1/chat/completions, y luego añade /chat/completions de nuevo.
2. El SDK recibe solo el dominio, como https://router.flatkey.ai, y nunca llega a la ruta /v1 compatible con OpenAI.

Para Python, pasa base_url o define OPENAI_BASE_URL. El código fuente oficial del cliente de Python también recurre a https://api.openai.com/v1 cuando no se proporciona una URL base personalizada.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["FLATKEY_API_KEY"],
    base_url=os.environ.get("FLATKEY_BASE_URL", "https://router.flatkey.ai/v1"),
)

response = client.chat.completions.create(
    model=os.environ["FLATKEY_MODEL"],
    messages=[{"role": "user", "content": "Reply with exactly: ok"}],
)

print(response.choices[0].message.content)

Para Node, pasa baseURL o define OPENAI_BASE_URL. El cliente oficial de Node documenta baseURL como la opción para sobrescribir la raíz predeterminada de la API de OpenAI.

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.FLATKEY_API_KEY,
  baseURL: process.env.FLATKEY_BASE_URL ?? "https://router.flatkey.ai/v1",
});

const response = await client.chat.completions.create({
  model: process.env.FLATKEY_MODEL!,
  messages: [{ role: "user", content: "Reply with exactly: ok" }],
});

console.log(response.choices[0]?.message?.content);

Si este paso de resolución de problemas de la API compatible con OpenAI sigue fallando, registra la URL base resuelta al inicio del proceso. No registres la clave.

Separa los nombres de modelo de las familias de endpoint

"Modelo no encontrado" puede significar que el alias es incorrecto, pero también puede significar que el alias se está enviando a la familia de endpoint equivocada. Un modelo que funciona para chat completions puede no estar expuesto mediante Responses, Messages, imágenes, video o embeddings con la misma forma de carga útil.

Ejecuta esta lista de verificación antes de cambiar nombres de modelo en producción:

Comprobación	Por qué importa
Confirma el alias exacto del modelo en la consola actual de Flatkey	Los alias del gateway pueden diferir de los nombres comerciales del proveedor directo
Confirma la familia de endpoint	/v1/chat/completions y /v1/responses tienen formas de solicitud diferentes
Elimina parámetros opcionales	Una opción no compatible puede ocultar el problema real del modelo
Prueba una solicitud corta sin streaming	Una solicitud simple aísla la ruta del análisis del stream
Registra el cuerpo que falla y la marca de tiempo	El soporte y la revisión de auditoría necesitan el modelo, la ruta y el error exactos

La documentación externa de modelos de OpenAI usa la misma idea para endpoints personalizados: proporciona una URL de endpoint, especifica slugs de modelo y ejecuta una llamada de verificación. Trata la configuración de tu gateway de la misma manera. Mantén en el código un pequeño mapa de modelos aprobados en lugar de permitir que cada servicio envíe cadenas de modelo sin procesar.

Depura el streaming después de que funcione sin streaming

El streaming debe ser una prueba de segunda etapa. La referencia de Chat Completions de OpenAI devuelve bien un objeto JSON de completions de chat o bien una secuencia transmitida de objetos chunk de completions de chat. La API de Responses también admite text/event-stream cuando stream está habilitado.

Usa una comprobación directa del stream:

curl -N "$FLATKEY_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$FLATKEY_MODEL"'",
    "stream": true,
    "messages": [
      {"role": "user", "content": "Count from one to five slowly."}
    ]
  }'

Si la solicitud sin streaming funciona y el stream no, inspecciona la ruta del stream:

• Confirma que la respuesta use un tipo de contenido compatible con SSE.
• Desactiva el middleware del cliente API que acumula toda la respuesta antes de devolverla.
• Desactiva el buffering del proxy inverso para esta ruta.
• Comprueba si tu parser de frontend espera chunks de Chat Completions mientras tu ruta devuelve eventos de Responses.
• Compara con la lista de verificación de streaming existente de Flatkey en /blog/openai-compatible-streaming-sse-test.

Este paso de resolución de problemas de la API compatible con OpenAI es especialmente importante en entornos sin servidor y herramientas de automatización. Algunos wrappers devuelven un estado HTTP correcto mientras ocultan el hecho de que no llegó ningún token al llamador hasta que el stream se cerró.

Añade herramientas solo después de que la solicitud base esté limpia

La llamada a herramientas añade otra capa de fallo. Un gateway, ruta o modelo seleccionado puede aceptar mensajes de chat simples pero rechazar un esquema de herramienta, tool_choice, llamadas paralelas a herramientas o ajustes estrictos de salida estructurada.

Usa una escalera de tres solicitudes:

1. Solicitud de texto plano con el mismo modelo.
2. La misma solicitud con un esquema de función pequeño.
3. Esquema completo de herramientas para producción.

Si la solicitud 1 funciona y la solicitud 2 falla, ya no estás depurando autenticación ni URL base. Estás depurando la capacidad del modelo, la familia de endpoint o la compatibilidad del esquema. Elimina campos opcionales, acorta las descripciones y verifica si la ruta del modelo seleccionado admite el comportamiento de herramientas que necesitas.

Demuestra la lectura de uso y facturación

No termine la solución de problemas de una API compatible con OpenAI en «la respuesta devolvió texto». Para una migración de producción, también necesita demostrar que la solicitud es visible donde los equipos de finanzas y operaciones la revisarán.

Después de una prueba de verificación exitosa, capture:

Evidencia	Qué demuestra
Marca de tiempo y ruta de la solicitud	Qué ruta de gateway recibió tráfico
Alias del modelo	Qué modelo configurado se solicitó
Estado de la respuesta e ID de solicitud	Qué puede rastrear el soporte
Objeto de uso o recuento de tokens	Si la aplicación puede registrar los factores de costo
Panel o lectura de facturación	Si finanzas puede conciliar el gasto
Evento de fallback o reintento, si lo hay	Si la política de enrutamiento cambió la ruta

Flatkey se posiciona en torno a una sola clave, precios claros, facturación unificada y un panel para claves, uso y enrutamiento. Para una migración, combine la prueba de verificación de ingeniería con una comprobación de lectura de uso en la consola antes de mover tráfico real.

Un flujo de trabajo de solución de problemas seguro para producción

Use esta secuencia cuando falle una migración de una API compatible con OpenAI:

1. Ejecute una solicitud curl sin streaming con la URL base actual de la consola, una clave y un alias de modelo aprobado.
2. Corrija cualquier 401 o 403 antes de cambiar los payloads.
3. Corrija la composición de la URL base antes de cambiar las versiones del SDK.
4. Corrija el alias del modelo y la familia del endpoint antes de cambiar la política de reintentos.
5. Agregue el SDK con api_key o apiKey explícito y base_url o baseURL.
6. Agregue streaming y verifique que el cliente reciba eventos incrementales.
7. Agregue herramientas o salida estructurada una característica a la vez.
8. Compruebe el uso y la lectura de facturación.
9. Traslade los valores que funcionan a una configuración lista para rollback.

Ese orden evita que la solución de problemas de una API compatible con OpenAI se convierta en una sesión de conjeturas. Cada paso o bien prueba una capa o le da un fallo más pequeño que corregir.

Cuándo ayuda Flatkey

Flatkey es útil cuando el problema de fondo es la dispersión operativa: demasiadas claves de proveedores, acceso inconsistente a modelos, uso difícil de revisar y rutas de facturación separadas. Un gateway unificado no elimina la necesidad de probar la familia del endpoint, el alias del modelo, el streaming, las herramientas y la lectura de facturación, pero sí le da al equipo un lugar para estandarizar esas comprobaciones.

Si está migrando una aplicación, combine esta guía con la guía de migración compatible con OpenAI de Flatkey en /blog/openai-compatible-api-migration y la lista de verificación de prueba de humo en /blog/ai-api-smoke-test-checklist.

Cuando esté listo para probar el flujo de trabajo con una clave de Flatkey, empiece en /sign-up y mantenga la primera prueba de humo lo bastante pequeña como para inspeccionarla manualmente.

Preguntas frecuentes

¿Por qué mi API compatible con OpenAI devuelve 401 cuando la clave está establecida?

El proceso puede estar leyendo una variable de entorno distinta de la que cambió, o la clave puede pertenecer al proveedor incorrecto. Compruebe el nombre de la variable resuelta, el encabezado Authorization: Bearer, los espacios en blanco copiados y cualquier política de cuenta o IP.

¿La URL base del SDK debería incluir /chat/completions?

Normalmente no. Dé al SDK la URL base de /v1 y luego deje que el SDK añada el endpoint. Pasar el endpoint completo suele crear rutas duplicadas.

¿Por qué un modelo funciona sin streaming pero falla con stream: true?

La ruta base puede ser correcta mientras la ruta de streaming está bloqueada por middleware de buffering, un desajuste del analizador SSE o una combinación de ruta/modelo que no admite streaming. Pruebe con curl -N antes de depurar el código del frontend.

¿Por qué aparece "model not found" con un nombre de modelo válido?

El alias puede ser válido en una familia de endpoint e inválido en otra, o el gateway puede exponer un alias diferente del proveedor directo. Confirme juntos el alias actual de la consola y la familia del endpoint.

¿Qué debería probar antes de enviar tráfico de producción?

Pruebe una solicitud sin streaming, una solicitud del SDK, un stream, una llamada de herramienta representativa si su aplicación usa herramientas, una ruta de fallo y un registro de facturación/lectura. Luego conserve una configuración de rollback para la ruta del proveedor anterior.

La solución de problemas de una API compatible con OpenAI no consiste en memorizar todos los errores de cada proveedor. Se trata de demostrar el recorrido desde la clave hasta la URL base, desde la URL base hasta la familia del endpoint, desde la familia del endpoint hasta el alias del modelo, y desde una respuesta exitosa hasta el registro de uso. Cuando esas capas están claras, cambiar el tráfico a través de Flatkey se convierte en una migración controlada en lugar de una sesión de depuración nocturna.