--- title: "Erros e códigos de erro da Public API" description: "Os erros da Public API chegam no array errors do GraphQL. Leia extensions.code, como Unauthorized ou NotEnoughPermissions, e guarde o traceId." canonical_url: https://chatfuel.com/pt/docs/public-api/errors markdown_url: https://chatfuel.com/pt/docs/public-api/errors.md last_updated: 2026-10-06 lang: pt site: https://chatfuel.com/docs llms_txt: https://chatfuel.com/llms.txt --- # Erros e códigos de erro da Public API Os erros da Public API chegam no array errors do GraphQL. Leia extensions.code, como Unauthorized ou NotEnoughPermissions, e guarde o traceId. 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 [#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: ```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" } } ] } } ] } ``` 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 [#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: ```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 } ``` ## Erros de autenticação e de permissão [#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](https://chatfuel.com/pt/docs/public-api/authentication), 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 [#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: | Código | Retornado por | O que fazer | | --------------------------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------- | | `VirtualUserRoleNotAllowed` | `createVirtualUser`, `changeBotMemberRoleV2` | Use a função `Editor` ou `Agent` | | `VirtualUserNameInvalid` | `createVirtualUser` | Use um nome de 1 a 100 caracteres | | `VirtualUsersLimitReached` | `createVirtualUser` | Remova os usuários virtuais que não estão em uso; o limite é de 20 por bot | | `NotVirtualUser` | `regenerateVirtualUserToken` | Passe o ID de membro de um usuário virtual, não o de um membro da equipe | | `VirtualUserNotAllowed` | Operações que um usuário virtual nunca pode realizar, como aceitar um convite | Execute a operação com um token de API pessoal | 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 [#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 [#problemas-comuns] ### "NotEnoughPermissions" em uma operação que funciona no painel [#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 [#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 [#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.