Erros e códigos de erro da Public API

A Public API do Chatfuel informa problemas no array errors padrão do GraphQL, normalmente com status HTTP 200. Cada erro traz um code legível por máquina nas suas extensions, como Unauthorized, NotEnoughPermissions ou um código de negócio como ContactDoesNotExist, além de um traceId que o suporte do Chatfuel pode usar para localizar a requisição. Baseie o tratamento de erros no código, nunca no texto da mensagem.

Como é uma resposta de erro

O gateway que fica na frente dos serviços do Chatfuel encapsula os erros que vêm de um serviço: o erro externo tem uma mensagem genérica, e os erros originais ficam em extensions.errors. Um usuário virtual que chama createVirtualUser recebe uma resposta 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"
            }
          }
        ]
      }
    }
  ]
}

As extensions internas podem conter:

• code: por que a operação falhou.
• service: o serviço do Chatfuel que respondeu.
• traceId: o ID de rastreamento da requisição. O mesmo valor é retornado no cabeçalho de resposta chatfuel-trace-id.
• data: em alguns erros de negócio, uma string JSON com detalhes, por exemplo, qual limite foi atingido.

Os erros gerados pelo próprio gateway, como um erro de sintaxe ou um campo desconhecido, chegam sem o encapsulamento e sem code; a message explica o problema. Quando alguns campos de uma consulta falham e outros funcionam, data contém as partes bem-sucedidas e errors descreve o restante.

Como ler os códigos de erro

Colete os códigos dos dois níveis para que o seu código funcione tanto com erros encapsulados quanto sem encapsulamento:

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
}

Erros de autenticação e de permissão

Estes dois códigos chegam com a mensagem auth error:

• Unauthorized: a requisição não tem um token válido. O token está ausente, foi digitado errado, foi revogado ou regenerado, falta Bearer no cabeçalho ou o usuário virtual foi removido.
• NotEnoughPermissions: o token é válido, mas o dono dele não pode executar esta operação. Ou um usuário virtual chamou uma operação que exige um token de API pessoal, ou a função não é suficiente, por exemplo, um Agent editando um fluxo. Também aparece quando o ID pertence a outro bot.

Códigos de erro de negócio

Os erros de negócio chegam com a mensagem service error e um código do enum DefinedErrorCode do esquema público. Cada página de referência lista os códigos que as suas operações podem retornar. Estes são os códigos mais comuns ao trabalhar com usuários virtuais:

Os outros códigos descrevem os dados: ContactDoesNotExist, ContactNoteTooLong, BookingEndTimeBeforeStartTime, GoodsItemTitleNotUnique, FileTooBig e assim por diante. Os nomes deles dizem o que corrigir.

Erros internos

InternalServerError, com a mensagem internal server error, significa que a requisição falhou do lado do Chatfuel. Tente novamente com backoff exponencial. Se continuar falhando, entre em contato com o suporte pelo chat no canto inferior direito do painel e informe o traceId e o horário da requisição.

Problemas comuns

"NotEnoughPermissions" em uma operação que funciona no painel

O painel é executado como você, com a sua função. A chamada de API é executada como o usuário virtual, com a função Editor ou Agent dele, e algumas operações nunca ficam disponíveis para usuários virtuais. Confira a função exigida pela operação na referência ou execute-a com o token de API pessoal.

"Unauthorized" logo depois de trocar um token

regenerateVirtualUserToken e Regenerate token no painel invalidam o token antigo imediatamente. Atualize todos os serviços que o utilizam.

A resposta tem "errors", mas o status HTTP é 200

Isso é normal no GraphQL. Considere uma resposta bem-sucedida somente quando errors não estiver presente.