> ## 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. # Gestionar códigos de error > Usa esta guía para clasificar las respuestas de error de CometAPI y aplicar pasos de reintento o corrección para fallos comunes de solicitudes. La gestión de errores de CometAPI es más sencilla cuando separas los **problemas de forma de la solicitud**, **problemas de autenticación**, **errores de ruta** y **fallos reintentables de la plataforma**. Usa la combinación de estado HTTP, `error.code` y `error.message` para decidir si debes corregir la solicitud o reintentarla. ## Triaje rápido | Status | Lo que normalmente significa | ¿Reintentar? | Primera acción | | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | -------------- | ---------------------------------------------------------------------------------------------------------------------- | | `400` | La validación de la solicitud falló antes de que se procesara normalmente. | No | Valida `model`, `messages`, la forma del JSON y los tipos de campo. | | `401` | La clave de API falta, está mal formada o no es válida. | No | Verifica `Authorization: Bearer $COMETAPI_KEY`. | | `403` | El acceso fue bloqueado o la solicitud actual no estaba permitida. | Normalmente no | Reintenta con una solicitud conocida que funcione y elimina primero los campos específicos del modelo. | | Error de ruta | URL base incorrecta o ruta de 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 mientras depuras. | | `429` | Limitación de tasa o saturación temporal. | Sí | Usa backoff exponencial con jitter. | | `500` con `error.code: invalid_request` | Una solicitud mal formada apareció a través de una respuesta con estado de servidor. | No | Corrige el cuerpo de la solicitud antes de reintentar. | | `500`, `503`, `504`, `524` | Fallo 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: ```json theme={null} { "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 falló la validación antes de que pudiera procesarse con normalidad. Causas comunes: * 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 Empieza 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: ```json theme={null} { "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](/es/overview/models). No asumas que toda solicitud de chat mal formada devuelve `400`. La ausencia de campos obligatorios de chat 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 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`: ```json theme={null} { "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í: ```json theme={null} { "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 clave funciona en la misma solicitud, trátalo como un problema de token, no como un problema de endpoint. ## `403 Forbidden` `403` suele ser una de estas situaciones: * 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 Qué hacer primero: 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. 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 aparecer 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: ```text theme={null} 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 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. Para un patrón de reintento reutilizable, consulta el ejemplo de backoff en [Chat Completions](/api/text/chat). ## `503`, `504`, and `524` Estos estados son **fallos del lado del servidor o de la clase de timeout**. Orientación práctica: * `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 Qué hacer: 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 Captura primero estos datos: * 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 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 el payload enviado 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 referenció mediante URL o se incrustó como base64 La forma más eficaz de reproducir un error es el payload exacto de la solicitud saneado. 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 de soporte.