Gestionar códigos de error

​

Triaje rápido

​

Envoltorio de error

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

​

400 Bad Request

• Faltan campos obligatorios como model
• Forma de 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

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

​

500 Internal Server Error

{
	"error": {
		"message": "field messages is required (request id: ...)",
		"type": "comet_api_error",
		"param": "",
		"code": "invalid_request"
	}
}

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.

​

401 Invalid Token

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

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 clave funciona en la misma solicitud, trátalo como un problema de token, no como un problema de endpoint.

​

403 Forbidden

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

1. Reintenta con una solicitud de texto muy simple contra un model que sepas que funciona.
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, consérvalo antes de contactar con soporte.

​

URL base incorrecta o ruta incorrecta

• 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

https://api.cometapi.com/v1

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

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

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

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

​

503, 504, and 524

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

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

​

Antes de contactar con soporte

• Método HTTP
• Ruta del endpoint
• ID 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 usó
• Cuerpo de la respuesta exacto 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

• 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 referenció mediante URL o se incrustó como base64