Solución de problemas

La mayoría de los problemas se muestran como un estado HTTP y un code en el cuerpo del error. Busca el código más abajo; Errores tiene la lista completa. Las peticiones fallidas (cualquier 4xx o 5xx) nunca se cobran.

{ "error": { "message": "...", "type": "authentication_error", "code": "invalid_api_key" } }

401 invalid_api_key

La clave falta, está mal formada o fue revocada.

• Envíala como Authorization: Bearer sk-api14-.... Los SDK de OpenAI lo hacen a partir de apiKey / api_key; con curl, comprueba que $API14_API_KEY esté realmente definida en el shell desde el que lo ejecutas (echo ${API14_API_KEY:0:9} debería mostrar sk-api14-).
• Cuidado con comillas o saltos de línea sobrantes cuando la clave viene de un archivo .env.
• Un OPENAI_API_KEY que quedó en el entorno puede sustituir a la clave que querías usar. Pasa la clave de forma explícita para descartarlo.
• Una clave revocada falla de inmediato. Las claves se muestran una sola vez, así que si perdiste una, crea una nueva en Claves de API y revoca la antigua.

Consulta Autenticación.

402 insufficient_balance

Tu saldo en USD es $0 o (en vídeo) inferior al coste estimado del trabajo. Las peticiones siguen bloqueadas hasta que añadas fondos; reintentar no ayuda.

• Comprueba el saldo con GET /credits o en Facturación. Consulta Saldo e información de la clave.
• Añade fondos o activa la recarga automática. Los planes añaden uso incluido al mismo saldo cada mes. Consulta Precios y facturación.
• En trabajos de larga duración, trata este código como fatal y detente, en lugar de dejar que los reintentos del SDK sigan girando.

403 model_not_allowed o plan_required

• model_not_allowed: la clave tiene una lista de modelos permitidos que no incluye este id de modelo. Edita la lista de la clave en Claves de API, o usa una clave sin ella. Los sufijos de variante cuentan: comprueba que el id exacto que envías esté permitido.
• plan_required: tu plan no incluye esta categoría de modelo. Los planes estándar cubren todas las categorías; revisa tu plan en la página de precios.

404 model_not_found o not_found

• model_not_found: el id del modelo es desconocido, está desactivado o fue retirado. Los ids incluyen el prefijo del proveedor: openai/gpt-5-mini, no gpt-5-mini. Busca el id exacto con GET /models o GET /models/{id} (no necesita clave). Consulta Ids de modelo y variantes.
• not_found: la ruta no existe, o el trabajo de vídeo o el id de generación no es tuyo. Normalmente indica una URL base incorrecta (ver abajo). Una consulta de generación justo después de una petición también puede devolver 404 durante unos segundos hasta que aparezca el registro.

URL base incorrecta

La URL base es exactamente:

https://api14.com/api/v1

Errores comunes:

Particularidades de las bibliotecas: ruby-openai añade v1 por sí misma, así que su uri_base es https://api14.com/api (Ruby); openai-go espera una barra final, https://api14.com/api/v1/ (Go).

429 rate_limited

Superaste el límite de peticiones por minuto de tu clave o plan (Free 5, Pro 100, Team 3.000, Enterprise 3.000+). La respuesta incluye Retry-After: 60.

• Espera el tiempo de Retry-After y reintenta con retroceso exponencial y jitter. Los SDK oficiales de OpenAI ya lo hacen (dos reintentos por defecto; aumenta maxRetries / max_retries).
• Para trabajos masivos, espacia las peticiones en lugar de lanzarlas todas a la vez, y agrupa varios elementos en una sola petición. Consulta Guía: procesamiento por lotes.
• Un 429 también puede venir del proveedor upstream, sobre todo en las variantes :free. Usa modelos de respaldo o enrutamiento de proveedores para repartir la carga.

429 daily_limit_reached

La clave alcanzó su límite diario de gasto en USD. Reintentar no ayuda hasta el siguiente día UTC. Aumenta o elimina el límite en Claves de API si el tráfico es esperado. Asegúrate de que tu lógica de reintentos distingue este código de rate_limited; de lo contrario, los trabajos seguirán reintentando en vano. Consulta Límites de tasa.

Tiempos de espera

Los modelos grandes, los modelos de razonamiento y las salidas largas pueden tardar minutos.

• Revisa el tiempo de espera de tu cliente. Los SDK de Node y Python usan 10 minutos por defecto; otros clientes HTTP suelen usar valores más cortos.
• Usa streaming en las generaciones largas. Los tokens empiezan a llegar en segundos y los tiempos de espera por inactividad de proxies y balanceadores de carga dejan de ser un problema. Consulta Streaming.
• Establece max_tokens y, para modelos de razonamiento, un esfuerzo de razonamiento menor.
• Si retransmites las peticiones por tu propio servidor, también se aplican los tiempos de espera de su proxy (por ejemplo proxy_read_timeout de nginx, que por defecto es de 60 segundos).
• Un tiempo de espera agotado en tu lado no cancela la generación en el proveedor, que aún puede facturarse. Usa la consulta de generaciones con el id de la petición para comprobarlo.

El streaming se desconecta o se detiene antes de tiempo

• Revisa finish_reason en el último fragmento. "length" significa que se alcanzó max_tokens; "error" significa que el proveedor falló a mitad del stream, y el fragmento incluye un objeto error. Reintenta o añade respaldos.
• Los proxies y las plataformas serverless a veces almacenan en búfer o cortan las respuestas SSE. Desactiva el búfer (X-Accel-Buffering: no en nginx) y comprueba la duración máxima de respuesta de la plataforma.
• Si analizas el stream tú mismo, ignora las líneas de comentario que empiezan por : (keep-alives) y detente en data: [DONE].
• Cerrar la conexión antes de tiempo no cancela el cobro: el proveedor puede terminar la generación de todos modos.

Errores CORS y aplicaciones de navegador

Nunca pongas una clave de API en código de navegador o móvil. Cualquiera puede leerla desde la página y gastar tu saldo. Llama a api14 desde tu propio backend y expón al navegador solo tu propio endpoint:

// server.js (Node / Express)
app.post("/api/chat", async (req, res) => {
  const stream = await client.chat.completions.create({
    model: "openai/gpt-5-mini",
    messages: req.body.messages, // valida y limita esta entrada
    stream: true,
  });
  for await (const chunk of stream) res.write(chunk.choices[0]?.delta?.content ?? "");
  res.end();
});

Un error CORS en el navegador durante el desarrollo suele deberse a una URL base incorrecta (la petición llegó al sitio web en lugar de a la API) o a una cabecera de petición personalizada que el preflight de la API no permite; mover la llamada a tu servidor resuelve ambos casos.

Problemas de versión del SDK

• openai de Python anterior a 1.0 usa openai.ChatCompletion.create y openai.api_base. Actualiza con pip install -U openai y usa el cliente OpenAI(base_url=..., api_key=...).
• Falta chat.completions.parse: las versiones 1.x/4.x anteriores solo tienen client.beta.chat.completions.parse. Actualiza el paquete.
• Errores de parámetro desconocido en el SDK para campos de la pasarela (provider, models, reasoning, plugins): pásalos con extra_body en Python, o con la opción equivalente de cuerpo adicional en otros SDK. Consulta Compatibilidad con el SDK de OpenAI.
• 400 del proveedor con un mensaje del proveedor: ese modelo o proveedor no admite el parámetro. Revisa supported_parameters del modelo en Modelos, o añade provider: { "require_parameters": true }.