Saltar al contenido principal

Documentation Index

Fetch the complete documentation index at: https://apidoc.cometapi.com/llms.txt

Use this file to discover all available pages before exploring further.

El manejo de errores de CometAPI es más sencillo cuando separas los problemas de forma de la solicitud, problemas de autenticación, errores de ruta y fallos de plataforma reintentables. Usa la combinación del estado HTTP, error.code y error.message para decidir si debes corregir la solicitud o reintentarla.

​
Triaje rápido

StatusLo que normalmente significa¿Reintentar?Primera acción
400La validación de la solicitud falló antes de que la solicitud se procesara normalmente.NoValida model, messages, la estructura JSON y los tipos de campo.
401La clave API falta, está mal formada o no es válida.NoComprueba Authorization: Bearer <COMETAPI_KEY>.
403El acceso fue bloqueado o la solicitud actual no estaba permitida.Normalmente noReintenta con una solicitud conocida que funcione y elimina primero los campos específicos del modelo.
Error de rutaURL base incorrecta o ruta del endpoint incorrecta. En Comet esto puede aparecer como una redirección 301 o HTML, no como un 404 JSON limpio.NoUsa https://api.cometapi.com/v1 exactamente y desactiva el seguimiento automático de redirecciones mientras depuras.
429Limitación de tasa o saturación temporal.SíUsa backoff exponencial con jitter.
500 con error.code: invalid_requestUna solicitud mal formada apareció a través de una respuesta con estado de servidor.NoCorrige el cuerpo de la solicitud antes de reintentar.
500, 503, 504, 524Fallo de plataforma, proveedor o de tipo timeout.SíReintenta con backoff y conserva el request id.

​
Envoltorio de error

Muchos fallos de CometAPI usan un cuerpo de error como este: 
{
	"error": {
		"message": "...",
		"type": "comet_api_error",
		"param": "",
		"code": "invalid_request"
	}
}
Algunas respuestas dejan code vacío. Cuando el estado es 500, trata error.code y error.message como la señal decisiva.

​
400 Bad Request

Un 400 normalmente significa que el cuerpo de la solicitud no superó la validación antes de que pudiera procesarse con normalidad. Causas comunes:
  • Faltan campos obligatorios como model
  • 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
Comienza con una solicitud mínima conocida que funcione y luego vuelve a añadir los campos opcionales uno por uno. Compara el payload con el esquema del endpoint en la referencia de la API. Usa una solicitud mínima como esta: 
{
	"model": "your-model-id",
	"messages": [
		{
			"role": "user",
			"content": "Hello"
		}
	]
}
Sustituye your-model-id por cualquier model ID actual de la página de modelos de CometAPI. No asumas que toda solicitud de chat mal formada devuelve 400. La ausencia de campos de chat obligatorios como messages también puede aparecer como 500 con error.code: invalid_request.

​
500 Internal Server Error

La mayoría de las respuestas 500 indican un fallo de plataforma o del proveedor. Para Chat Completions, algunas solicitudes mal formadas también pueden aparecer como 500 y aun así incluir error.code: invalid_request. Un ejemplo es una solicitud que omite messages: 
{
	"error": {
		"message": "field messages is required (request id: ...)",
		"type": "comet_api_error",
		"param": "",
		"code": "invalid_request"
	}
}
Si una respuesta 500 tiene error.code: invalid_request, trátala como un problema de solicitud:
  1. Corrige el cuerpo de la solicitud.
  2. Compara el payload con el esquema del endpoint.
  3. Reintenta solo después de corregir el payload.
Si una respuesta 500 no apunta a una solicitud no válida, conserva el request id y usa backoff.

​
401 Invalid Token

Un fallo de token normalmente se ve así: 
{
	"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

403 suele corresponder a una de estas situaciones:
  • La solicitud está bloqueada por una regla del lado de la plataforma, como un filtrado WAF
  • El token o la ruta no tienen permiso para usar el model solicitado o la forma de solicitud requerida
  • El model elegido rechaza uno de los parámetros avanzados que enviaste
Qué hacer primero:
  1. Reintenta con una solicitud de texto muy simple contra un model conocido que funcione.
  2. Elimina los campos avanzados y los parámetros específicos del proveedor, y luego vuelve a agregarlos gradualmente.
  3. Si la respuesta incluye un request id, guárdalo 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 model y la forma de la solicitud.

​
URL base incorrecta o ruta incorrecta

En Comet, un error en la ruta puede manifestarse como:
  • Una redirección
  • Una respuesta HTML no JSON si tu cliente sigue 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 incluya /v1.
  2. Confirma que la ruta del endpoint coincida exactamente con la documentación.
  3. Desactiva el seguimiento automático de redirecciones mientras depuras problemas de ruta.

​
413 Request Entity Too Large

Si ves 413, trátalo primero como un problema de tamaño de la solicitud. Los sospechosos habituales son:
  • Cargas útiles base64 grandes
  • 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

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é model se están saturando primero.
Para un patrón de reintento reutilizable, consulta el ejemplo de backoff en Chat Completions.

​
503, 504, and 524

Estos estados son fallos del lado del servidor o de la clase de timeout. Guía práctica:
  • 503: la ruta o el servicio del proveedor no están disponibles temporalmente
  • 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 model y la marca de tiempo.
  3. Si el mismo fallo se repite en varios reintentos, contacta con soporte con ese contexto.

​
Antes de contactar con soporte

Captura primero estos detalles:
  • Método HTTP
  • Ruta del endpoint
  • Model ID
  • JSON del cuerpo de la solicitud sanitizado (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 usó
  • 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 u otro token
Si la ruta que falló acepta subidas de archivos (edición de imágenes, subida de audio, generación de video, etc.) en lugar de un cuerpo JSON simple, envía la carga útil equivalente que se envió:
  • Nombres de campo 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 referenció mediante URL o se incrustó como base64
La forma más efectiva de reproducir un error es la carga útil exacta de la solicitud sanitizada. 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 subida de archivos, eso significa la lista de campos más los metadatos del archivo.
Esto acorta significativamente el tiempo de respuesta de soporte.