Errores y códigos de error de la Public API

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

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:

{
  "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

Recoge los códigos de ambos niveles para que tu código funcione tanto con errores envueltos como sin envolver:

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

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, 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

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:

Los demás códigos describen los datos: ContactDoesNotExist, ContactNoteTooLong, BookingEndTimeBeforeStartTime, GoodsItemTitleNotUnique, FileTooBig, etc. Sus nombres indican qué corregir.

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

"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

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

Es lo normal en GraphQL. Considera que una respuesta fue exitosa solo cuando no incluye errors.