Solución de problemas

Empieza por el síntoma y luego aplica la corrección. La mayoría de los fallos se deben a la URL base, la clave, el ID de modelo o el saldo.

Tabla basada en síntomas

Autenticación

Una clave revocada devuelve un mensaje que indica el prefijo de la clave:

{
  "status": 401,
  "code": "UNAUTHORIZED",
  "message": "API Key has been revoked (keyPrefix=...)"
}

Lista de comprobación:

• El encabezado es Authorization: Bearer <key> para Model API y las API de Felo.
• La Data API también acepta X-API-Key: <key>.
• La clave no está entre comillas y no tiene un salto de línea final por haberse copiado desde una variable de entorno.
• El entorno desplegado tiene realmente la variable definida; una clave que funciona en local puede faltar en producción.
• La clave no se ha eliminado ni rotado. Una clave eliminada o rotada no puede volver a mostrarse; crea una nueva.

Consulta Autenticación para ver la creación de claves y los límites.

Trampas de la URL base

Dos errores habituales:

1. Añadir /chat/completions a una URL base que el SDK ya amplía.
2. Definir la URL base de Anthropic como https://openapi.felo.ai/api/v1. El SDK añade /v1/messages, por lo que la solicitud pasa a ser /api/v1/v1/messages.

Problemas con el ID de modelo

Los ID de modelo son los ID públicos del catálogo, no los nombres internos del proveedor upstream ni un nombre visible.

• Busca el ID en la página de modelos o en GET /api/v1/models.
• Confirma que el modelo admite el protocolo que estás llamando (supported_protocols).
• Si fijaste un canal, confirma que ese canal está publicado y se puede ejecutar para ese modelo. Un canal no disponible no es una alternativa de respaldo.

Consulta Canales y enrutamiento de proveedores.

Problemas de streaming

• Define stream: true en el cuerpo de la solicitud, no como parámetro de consulta.
• Lee el cuerpo de la respuesta como un flujo. Esperar la respuesta completa anula el streaming.
• Algunos proxies y plataformas sin servidor almacenan las respuestas en búfer. Desactiva el almacenamiento en búfer en la ruta que hace de proxy de la solicitud.
• Chat Completions transmite choices[0].delta, no choices[0].message. El contenido final llega repartido en muchos fragmentos.
• Un flujo puede terminar sin un evento terminal limpio si se corta la conexión. Trata una conexión interrumpida como una respuesta incompleta.

Problemas con tareas asíncronas

• Consulta el endpoint de estado que corresponde a la familia de la tarea. Los flujos de Felo usan GET /v2/tasks/{task_id}/status; las tareas de video e imagen de modelos usan sus propios endpoints de generación.
• Detente en todos los estados terminales, incluidos los fallos y las caducidades, no solo en el éxito.
• Actualmente se ignoran las devoluciones de llamada de video e imagen. No esperes un webhook.
• La URL de un resultado puede tener una vigencia corta. Solicita una URL nueva al endpoint de estado si una descarga caduca.
• Comprueba la tarea antes de volver a enviarla. Volver a enviar una tarea en ejecución crea un duplicado y se facturan ambos.

Consulta Tareas asíncronas.

Problemas con la Data API

• Mantén la ruta del método exacta de la referencia de la Data API.
• Los cuerpos de las solicitudes son específicos de cada proveedor. Un campo que funciona para un proveedor no tiene por qué funcionar para otro.
• Un error del proveedor puede llegar dentro de una respuesta 4xx con un mensaje específico del proveedor. Registra request_id y el cuerpo de la respuesta.

Recordatorios de seguridad

• Nunca pongas una clave de API en código de navegador, en el paquete de una aplicación móvil ni en un repositorio público. Mantenla en un servidor y enruta las solicitudes mediante un proxy.
• No registres la clave completa. Registra un prefijo si necesitas identificarla.
• Rota una clave de inmediato si puede haberse filtrado.

Antes de contactar con soporte

Reúne:

1. Endpoint y método HTTP.
2. Estado HTTP, code y request_id.
3. ID de modelo o ID de tarea.
4. Marca temporal con zona horaria.
5. Un cuerpo de solicitud mínimo sin los secretos.

Envíalo a soporte junto con el correo electrónico de la cuenta. No incluyas la clave de API completa.

Relacionado

• Errores, límites y reintentos
• Protocolos y SDK
• Facturación y créditos
• Autenticación