Códigos de error y manejo

Soluciona fallos de solicitudes de CometAPI con orientación verificada para errores 400, 401 y de ruta, además de manejo práctico para fallos 403, 429 y de tipo timeout.

El manejo de errores de CometAPI es más sencillo cuando separas los problemas de solicitud, los problemas de autenticación y los problemas de plataforma reintentables. Esta página es la guía canónica de errores de CometAPI y se centra en lo que puedes verificar primero desde el lado del cliente.

Esta guía se basa en comprobaciones en vivo contra la API actual de CometAPI. Verificamos directamente fallos de 400, 401 y de ruta/base URL. No reproducimos 413, 429, 500, 503, 504 ni 524 en pruebas acotadas, por lo que la orientación para esos estados es intencionalmente conservadora.

​

Triaje rápido

Status	Lo que normalmente significa	¿Reintentar?	Primera acción
400	La validación de la solicitud falló antes de que la solicitud se enrutara correctamente.	No	Valida model, messages, la estructura JSON y los tipos de campo.
401	La API key falta, está mal formada o no es válida.	No	Comprueba Authorization: Bearer <COMETAPI_KEY>.
403	El acceso fue bloqueado o la solicitud actual no estaba permitida.	Normalmente no	Reintenta con una solicitud conocida como válida y elimina primero los campos específicos del modelo.
Path mistake	Base URL incorrecta o ruta del endpoint incorrecta. En Comet esto puede aparecer como una redirección 301 o HTML, no como un 404 JSON limpio.	No	Usa https://api.cometapi.com/v1 exactamente y desactiva el seguimiento automático de redirecciones durante la depuración.
429	Limitación de tasa o saturación temporal.	Sí	Usa exponential backoff con jitter.
500, 503, 504, 524	Fallo de plataforma o de tipo timeout.	Sí	Reintenta con backoff y conserva el request id.

​

Envoltorio de error

El envoltorio de error JSON actual que devuelve CometAPI se ve así:

{
	"error": {
		"code": "",
		"message": "...",
		"type": "comet_api_error"
	}
}

Muchos mensajes de error observados en vivo también incluyen un request id dentro de error.message. Guarda ese valor cuando necesites soporte.

​

400 Bad Request

Esto es lo que observamos en la API en vivo cuando se omitió model:

{
	"error": {
		"code": "",
		"message": "model name is required (request id: ...)",
		"type": "comet_api_error"
	}
}

En la práctica, 400 normalmente significa que el cuerpo de la solicitud no superó la validación antes de que la plataforma pudiera enrutarla al proveedor del modelo.

Causas comunes:

• Faltan campos obligatorios como model o messages
• Estructura JSON no válida
• Envío de un campo con el tipo incorrecto
• Reutilización de parámetros específicos del proveedor que el endpoint seleccionado no acepta

Qué hacer:

1. Empieza con una solicitud mínima conocida como válida.
2. Vuelve a añadir los campos opcionales uno por uno.
3. Compara el cuerpo de la solicitud con el esquema del endpoint en la referencia de la API.

Ejemplo mínimo conocido como válido:

{
	"model": "your-model-id",
	"messages": [
		{
			"role": "user",
			"content": "Hello"
		}
	]
}

Sustituye your-model-id por cualquier ID de modelo actual de la página de modelos de CometAPI.

​

401 Invalid Token

Esto es lo que observamos en la API en vivo con una clave no válida:

{
	"error": {
		"code": "",
		"message": "invalid token (request id: ...)",
		"type": "comet_api_error"
	}
}

Qué comprobar:

1. El encabezado debe ser exactamente Authorization: Bearer <COMETAPI_KEY>.
2. Asegúrate de que tu aplicación no esté cargando una clave antigua desde .env, el historial del shell o un almacén de secretos desplegado.
3. Si una clave falla y otra funciona en la misma solicitud, trátalo como un problema de token, no como un problema del endpoint.

​

403 Forbidden

No reprodujimos un 403 estable en pruebas acotadas, así que evita tratar una única plantilla de mensaje antigua como si contara toda la historia.

En la documentación actual de Comet, 403 suele tratarse con mayor frecuencia como una de estas situaciones:

• La solicitud está bloqueada por una regla del lado de la plataforma, como el filtrado de WAF
• El token o la ruta no tienen permitido usar el modelo solicitado o la forma de solicitud requerida
• El modelo elegido rechaza uno de los parámetros avanzados que enviaste

Qué hacer primero:

1. Reintenta con una solicitud de texto muy simple contra un modelo conocido que funcione bien.
2. Elimina los campos avanzados y los parámetros específicos del proveedor, y luego agrégalos de nuevo gradualmente.
3. Si la respuesta incluye un request id, consérvalo antes de contactar con soporte.

Si el mensaje menciona términos internos como group o channel, trátalos como detalles de enrutamiento, no como lo primero que debes diagnosticar desde el lado del cliente. La solución práctica sigue siendo validar primero el token, el modelo y la forma de la solicitud.

​

URL base incorrecta o ruta incorrecta

Esta es el área en la que la página antigua era menos precisa.

En comprobaciones en vivo contra los endpoints actuales de Comet:

• Hacer una solicitud POST a https://api.cometapi.com/chat/completions devolvió una redirección 301 a https://www.cometapi.com/chat/completions
• Hacer una solicitud POST a una ruta de API falsa como https://api.cometapi.com/v1/not-a-real-endpoint también devolvió una redirección 301 a https://www.cometapi.com/v1/not-a-real-endpoint

Eso significa que un error en la ruta puede manifestarse como:

• Una redirección
• Una respuesta HTML no JSON si tu cliente sigue las redirecciones
• Un error de análisis dentro de tu SDK
• Una solicitud que nunca llega limpiamente a la capa de API

Usa esta URL base exactamente:

https://api.cometapi.com/v1

Comprobaciones recomendadas:

1. Confirma que la URL base incluye /v1.
2. Confirma que la ruta del endpoint coincide exactamente con la documentación.
3. Desactiva el seguimiento automático de redirecciones mientras depuras problemas de ruta.

​

413 Request Entity Too Large

No reprodujimos 413 en una prueba acotada, ni siquiera con un cuerpo de solicitud JSON sobredimensionado de 8 MiB, así que la explicación antigua de que el prompt era demasiado largo era demasiado limitada.

Si llegas a ver un 413, trátalo primero como un problema de tamaño de la solicitud. Los sospechosos habituales son:

• Cargas útiles grandes en base64
• Imágenes o audio demasiado grandes incrustados en línea
• Cuerpos multipart o JSON muy grandes

Qué hacer:

1. Reduce o comprime el contenido adjunto.
2. Divide los trabajos grandes en solicitudes más pequeñas.
3. No asumas que la longitud del texto plano es la única causa.

​

429 Too Many Requests

No reprodujimos 429 durante una prueba acotada de concurrencia con 24 solicitudes paralelas GET /v1/models, así que el umbral exacto claramente depende de la ruta, el modelo y el estado actual de la plataforma.

Trata 429 como reintentable:

1. Usa exponential backoff con jitter.
2. Reduce la concurrencia en ráfaga.
3. Mantén activado el registro de solicitudes para que puedas ver qué ruta y qué modelo se están saturando primero.

Para un patrón de reintento reutilizable, consulta el ejemplo de backoff en Chat Completions.

​

500, 503, 504 y 524

No reprodujimos estos estados en pruebas acotadas. Deben documentarse como fallos del lado del servidor o de la clase timeout, no como errores del usuario.

Guía práctica:

• 500: fallo interno de la plataforma o del lado del proveedor
• 503: ruta o servicio del proveedor temporalmente no disponible
• 504 y 524: fallos de tipo timeout entre la plataforma, el edge o el servicio del proveedor

Qué hacer:

1. Reintenta con backoff.
2. Conserva el request id, el endpoint, el modelo y la marca de tiempo.
3. Si el mismo fallo se repite en varios reintentos, contacta con soporte con ese contexto.

​

Antes de Contactar al Soporte

Captura primero estos detalles:

• Método HTTP
• Ruta del endpoint
• Nombre del modelo
• JSON del cuerpo de la solicitud saneado (este es el elemento más útil para la mayoría de las llamadas a la API)
• Parámetros de consulta si la solicitud que falló los utilizó
• Cuerpo exacto de la respuesta si tu cliente lo capturó
• Estado HTTP completo
• El error.message exacto
• Cualquier request id
• Marca de tiempo aproximada
• Si la misma solicitud funciona con otro modelo o con otro token

Si la ruta que falló acepta cargas de archivos (edición de imágenes, carga de audio, generación de video, etc.) en lugar de un cuerpo JSON simple, envía la carga útil enviada equivalente:

• Nombres de los campos y valores de texto que enviaste junto con el archivo
• Nombre del archivo, tipo de archivo y tamaño aproximado del archivo
• Si el archivo se subió directamente, se hizo referencia a él mediante URL o se incrustó como base64

La forma más rápida de reproducir un bug es la carga útil exacta de la solicitud saneada. Para la mayoría de las llamadas a la API, eso significa el JSON del cuerpo de la solicitud sin procesar. Para las rutas de carga de archivos, eso significa la lista de campos más los metadatos del archivo.

Esto acorta significativamente el tiempo de respuesta del soporte.