Si algo no funciona, la forma más rápida de saber si el problema es tuyo o nuestro es ejecutar la misma solicitud desde una herramienta diferente.

Aproximadamente 9 de cada 10 informes de «API rota» resultan ser una URL base mal configurada, una clave de API antigua, un nombre de modelo incorrecto, o un cuerpo de solicitud de un tutorial desactualizado tres versiones del SDK.

Prueba rápida de autodiagnóstico

Copia este comando curl en una terminal. Sustituye YOUR_KEY por tu clave de API del dashboard y ejecútalo. Si recibes una respuesta normal, tu clave de API, la red y nuestro backend están todos en buen estado — cualquier problema está en el código o entorno de tu cliente.

cURL

curl https://api.airforce/v1/chat/completions \
  -H "Authorization: Bearer sk-air-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4.1-mini",
    "messages": [{"role": "user", "content": "ping"}]
  }'

ℹ️

Prueba rápida de autodiagnóstico: ¿No tienes terminal a mano? Pega el mismo modelo + prompt en el Playground desde el dashboard — mismo efecto, sin configuración.

Lista de verificación paso a paso

¿Tu clave de API es válida?

Abre Dashboard → API Keys y confirma que la clave coincide con la que usa tu código. Un error común es el espacio en blanco antes del prefijo "sk-air-" al copiar y pegar.

Síntoma: 401 Unauthorized.

¿La URL base es correcta?

La URL base debe ser https://api.airforce/v1 — no http, y el sufijo /v1 es obligatorio. Los tutoriales anteriores a la ruta v1 de OpenAI a veces lo omiten.

Síntoma: 404 Not Found, o curl se queda colgado.

¿El nombre del modelo está escrito correctamente?

Los IDs de modelo distinguen entre mayúsculas y minúsculas. Visita la página de Models o llama a GET /v1/models para confirmar el ID exacto. Un error tipográfico o un modelo que ha sido deprecado devuelve un error claro en lugar de «funcionar pero incorrectamente».

Síntoma: 400 unknown_model o 404 model_not_found.

¿El cuerpo de la solicitud tiene la forma correcta?

Las completaciones de chat usan un array messages. Las imágenes usan prompt + n. El audio TTS usa input + voice. Enviar un cuerpo con formato de chat a /v1/images/generations devuelve 400 — fácil de pasar por alto al copiar fragmentos entre documentos.

Síntoma: 400 con el campo problemático nombrado en el cuerpo de la respuesta.

¿Has alcanzado un límite de tasa o cuota?

429 = demasiadas solicitudes en este minuto. 402 = tu plan o saldo está agotado. Ambos se muestran en el Dashboard. Las solicitudes del nivel gratuito tienen límites separados de las solicitudes de plan de pago, por lo que un modelo de pago puede responder bien mientras uno gratuito aplica límite de tasa.

Síntoma: 429 Too Many Requests o 402 Payment Required.

¿El modelo está realmente disponible ahora?

Consulta la página de Models — las interrupciones de proveedor aparecen como «degraded» o «major outage». Si un modelo está caído mientras otros funcionan, es un problema del lado del proveedor que nosotros enrutamos alrededor, no un error del cliente.

Síntoma: un modelo específico devuelve 5xx mientras otros funcionan.

Qué significan los códigos de estado HTTP

Cada respuesta de error lleva un código de estado HTTP estándar. Saber lo que indica cada uno te ahorra abrir un ticket.


400	Tu lado	Bad Request — JSON mal formado, campo requerido faltante, parámetro desconocido. Corrige el cuerpo de la solicitud.
401	Tu lado	Unauthorized — clave de API faltante o inválida. Verifica que la cabecera Authorization incluya el prefijo "Bearer ".
402	Tu lado	Payment Required — plan agotado o saldo de Pay-as-you-go vacío. Suscríbete o recarga.
403	Tu lado	Forbidden — tu plan o permiso por clave no permite este modelo o endpoint.
404	Tu lado	Not Found — endpoint o ID de modelo desconocido. Verifica la ruta URL y la ortografía del modelo.
413	Tu lado	Payload Too Large — la entrada supera la ventana de contexto del modelo. Acorta el prompt.
429	Tu lado	Too Many Requests — límite de tasa alcanzado (RPM, RPD o cuota diaria de tokens). Reduce la velocidad o mejora tu plan.
500	Nuestro lado	Internal Server Error — un bug de nuestro lado. Repórtalo si persiste más de un minuto.
502	Nuestro lado	Bad Gateway — backend reiniciándose (hacemos despliegues varias veces al día). Espera 5–10 segundos y reintenta.
503	Nuestro lado	Service Unavailable — todos los proveedores upstream para ese modelo fallaron a la vez. Repórtalo si dura más de unos minutos.

💡

Regla general: Los códigos 4xx significan que tu cliente hizo algo que el servidor rechazó. Los códigos 5xx significan que fallamos al manejar una solicitud válida. El cuerpo de error JSON en la respuesta generalmente nombra el campo que activó la verificación.

Cuándo es realmente un bug

Si la autoprueba con curl funciona pero exactamente la misma solicitud desde tu código no funciona, el problema está en tu cliente (o la biblioteca que usa). Si la autoprueba falla con un error 5xx, o devuelve un 4xx con un mensaje que no coincide con lo que parece tu solicitud, vale la pena reportarlo.

Cómo reportar de forma efectiva

Abre un ticket de soporte desde el dashboard o publica en #support de Discord. Incluye:

El código de estado HTTP completo y el cuerpo de la respuesta (también la cabecera de respuesta cf-ray, si está presente).
Marca de tiempo aproximada en UTC.
El nombre del modelo y el endpoint que llamaste.
Un cURL mínimo que lo reproduzca (¡enmascara tu clave de API real!).
Si la autoprueba anterior funciona para ti con la misma clave.

ℹ️

Cómo reportar de forma efectiva: Los tickets que llegan con estos detalles reciben una respuesta real al primer intento. Los tickets sin ellos casi siempre requieren un intercambio antes de que podamos ayudar.

Pregunta en #support de Discord

Antes de reportar un bug