--- title: "Errores y códigos de error de la Public API" description: "Los errores de la Public API llegan en el arreglo errors de GraphQL. Lee extensions.code, como Unauthorized o NotEnoughPermissions, y guarda el traceId." canonical_url: https://chatfuel.com/es/docs/public-api/errors markdown_url: https://chatfuel.com/es/docs/public-api/errors.md last_updated: 2026-10-06 lang: es site: https://chatfuel.com/docs llms_txt: https://chatfuel.com/llms.txt --- # Errores y códigos de error de la Public API Los errores de la Public API llegan en el arreglo errors de GraphQL. Lee extensions.code, como Unauthorized o NotEnoughPermissions, y guarda el traceId. La Public API de Chatfuel informa los problemas en el arreglo `errors` estándar de GraphQL, normalmente con el estado HTTP 200. Cada error lleva un `code` legible por máquinas en sus `extensions`, como `Unauthorized`, `NotEnoughPermissions` o un código de negocio como `ContactDoesNotExist`, además de un `traceId` que el soporte de Chatfuel puede usar para encontrar la solicitud. Basa tu manejo de errores en el código, nunca en el texto del mensaje. ## Cómo se ve una respuesta de error [#cómo-se-ve-una-respuesta-de-error] El gateway que está delante de los servicios de Chatfuel envuelve los errores que vienen de un servicio: el error externo tiene un mensaje genérico y los errores originales están en `extensions.errors`. Un usuario virtual que llama a `createVirtualUser` recibe una respuesta como esta: ```json { "data": null, "errors": [ { "message": "Failed to fetch from Subgraph 'useraccounting'.", "extensions": { "errors": [ { "message": "auth error", "path": ["createVirtualUser"], "extensions": { "code": "NotEnoughPermissions", "service": "useraccounting", "traceId": "4bf92f3577b34da6a3ce929d0e0e4736" } } ] } } ] } ``` Las `extensions` internas pueden contener: * `code`: por qué falló la operación. * `service`: el servicio de Chatfuel que respondió. * `traceId`: el ID de traza de la solicitud. El mismo valor se devuelve en el encabezado de respuesta `chatfuel-trace-id`. * `data`: en algunos errores de negocio, una cadena JSON con detalles, por ejemplo, qué límite se alcanzó. Los errores que genera el propio gateway, como un error de sintaxis o un campo desconocido, llegan sin el envoltorio y sin `code`; el `message` explica el problema. Cuando algunos campos de una consulta fallan y otros funcionan, `data` contiene las partes exitosas y `errors` describe el resto. ## Cómo leer los códigos de error [#cómo-leer-los-códigos-de-error] Recoge los códigos de ambos niveles para que tu código funcione tanto con errores envueltos como sin envolver: ```js function errorCodes(errors = []) { return errors.flatMap((error) => [ error.extensions?.code, ...(error.extensions?.errors ?? []).map((inner) => inner.extensions?.code), ]).filter(Boolean); } const body = await res.json(); const codes = errorCodes(body.errors); if (codes.includes('Unauthorized')) { // refresh or replace the token } ``` ## Errores de autenticación y de permisos [#errores-de-autenticación-y-de-permisos] Estos dos códigos llegan con el mensaje `auth error`: * `Unauthorized`: la solicitud no tiene un token válido. El token falta, está mal escrito, fue revocado o regenerado, al encabezado le falta `Bearer ` o el usuario virtual fue eliminado. * `NotEnoughPermissions`: el token es válido, pero su propietario no puede ejecutar esta operación. O bien un usuario virtual llamó a una operación que requiere un [token de API personal](https://chatfuel.com/es/docs/public-api/authentication), o bien el rol no alcanza, por ejemplo, un Agent que edita un flujo. También aparece cuando el ID pertenece a otro bot. ## Códigos de error de negocio [#códigos-de-error-de-negocio] Los errores de negocio llegan con el mensaje `service error` y un código del enum `DefinedErrorCode` del esquema público. Cada página de referencia enumera los códigos que pueden devolver sus operaciones. Estos son los códigos que encontrarás con más frecuencia al trabajar con usuarios virtuales: | Código | Lo devuelve | Qué hacer | | --------------------------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- | | `VirtualUserRoleNotAllowed` | `createVirtualUser`, `changeBotMemberRoleV2` | Usa el rol `Editor` o `Agent` | | `VirtualUserNameInvalid` | `createVirtualUser` | Usa un nombre de 1 a 100 caracteres | | `VirtualUsersLimitReached` | `createVirtualUser` | Elimina los usuarios virtuales que no uses; el límite es de 20 por bot | | `NotVirtualUser` | `regenerateVirtualUserToken` | Pasa el ID de miembro de un usuario virtual, no el de un compañero de equipo | | `VirtualUserNotAllowed` | Operaciones que un usuario virtual nunca puede realizar, como aceptar una invitación | Ejecuta la operación con un token de API personal | Los demás códigos describen los datos: `ContactDoesNotExist`, `ContactNoteTooLong`, `BookingEndTimeBeforeStartTime`, `GoodsItemTitleNotUnique`, `FileTooBig`, etc. Sus nombres indican qué corregir. ## Errores internos [#errores-internos] `InternalServerError`, con el mensaje `internal server error`, significa que la solicitud falló del lado de Chatfuel. Vuelve a intentarlo con backoff exponencial. Si sigue fallando, contacta al soporte desde el chat de la esquina inferior derecha del panel e incluye el `traceId` y la hora de la solicitud. ## Problemas comunes [#problemas-comunes] ### "NotEnoughPermissions" en una operación que funciona en el panel [#notenoughpermissions-en-una-operación-que-funciona-en-el-panel] El panel se ejecuta como tú, con tu rol. La llamada a la API se ejecuta como el usuario virtual, con su rol Editor o Agent, y algunas operaciones nunca están disponibles para los usuarios virtuales. Revisa el rol de la operación en la referencia o ejecútala con el token de API personal. ### "Unauthorized" justo después de rotar un token [#unauthorized-justo-después-de-rotar-un-token] `regenerateVirtualUserToken` y **Regenerate token** en el panel invalidan el token anterior de inmediato. Actualiza todos los servicios que lo usan. ### La respuesta tiene "errors" pero el estado HTTP es 200 [#la-respuesta-tiene-errors-pero-el-estado-http-es-200] Es lo normal en GraphQL. Considera que una respuesta fue exitosa solo cuando no incluye `errors`.