Cadastrar-se
Contato Entrar Cadastrar-se
Status do Sistema

Referência abrangente de todos os códigos de erro na API GraphQL da Blue, organizada por categoria

Formato de Resposta de Erro

A API GraphQL da Blue retorna erros em um formato padronizado seguindo a especificação GraphQL. Quando um erro ocorre, a resposta inclui um array errors com informações detalhadas sobre o que deu errado.

Exemplo de Resposta de Erro

{
  "errors": [
    {
      "message": "Todo was not found.",
      "extensions": {
        "code": "TODO_NOT_FOUND"
      }
    }
  ]
}

Estrutura do Erro

Cada objeto de erro contém:

  • mensagem: Uma descrição legível por humanos do erro
  • extensions.code: Um código de erro legível por máquina para tratamento programático

Segurança de Erro em Produção

A Blue implementa um sistema de segurança para exposição de erros:

  • Erros Seguros: Exibir códigos e mensagens de erro reais para os clientes
  • Erros Não-Seguros: Retornar INTERNAL_SERVER_ERROR genéricos para ocultar detalhes sensíveis
  • Recurso Não Encontrado: Todos os erros *_NOT_FOUND são considerados seguros e sempre expostos

Categorias de Erro

A Blue define 108 códigos de erro personalizados organizados nas seguintes categorias:

Erros de Autenticação e Autorização

Código de Erro Mensagem Descrição
UNAUTHENTICATED "Autenticação requerida." A solicitação requer autenticação, mas nenhuma foi fornecida
FORBIDDEN "Você não está autorizado." Autenticado, mas sem as permissões necessárias

Erros de Recurso Não Encontrado (52 no total)

Recursos Principais

Código de Erro Mensagem Descrição
TODO_NOT_FOUND "Todo não foi encontrado." Registro/todo não existe ou o usuário não tem acesso
TODO_LIST_NOT_FOUND "Lista de tarefas não foi encontrada." Lista não existe ou o usuário não tem acesso
PROJECT_NOT_FOUND "Projeto não foi encontrado." Projeto não existe ou o usuário não tem acesso
COMPANY_NOT_FOUND "Empresa não foi encontrada." Empresa não existe ou o usuário não tem acesso
USER_NOT_FOUND "Usuário não foi encontrado." Usuário não existe no sistema

Campos e Formulários Personalizados

Código de Erro Mensagem Descrição
CUSTOM_FIELD_NOT_FOUND "Campo personalizado não foi encontrado." Campo personalizado não existe
CUSTOM_FIELD_OPTION_NOT_FOUND "Opção de campo personalizado não foi encontrada." Opção de campo de seleção não existe
FORM_NOT_FOUND "Formulário não foi encontrado." Modelo de formulário não existe
FORM_FIELD_NOT_FOUND "Campo do formulário não foi encontrado." Campo do formulário não existe

Componentes do Projeto

Código de Erro Mensagem Descrição
TAG_NOT_FOUND "Tag não foi encontrada." Tag não existe no projeto
AUTOMATION_NOT_FOUND "Automação não foi encontrada." Regra de automação não existe
CHART_NOT_FOUND "Gráfico não foi encontrado." Gráfico do painel não existe
WEBHOOK_NOT_FOUND "Webhook não foi encontrado." Configuração do webhook não existe
TEMPLATE_NOT_FOUND "Modelo não foi encontrado." Modelo de projeto não existe

Comentários e Atividades

Código de Erro Mensagem Descrição
COMMENT_NOT_FOUND "Comentário não foi encontrado." Comentário não existe
ACTIVITY_NOT_FOUND "Atividade não foi encontrada." Registro de log de atividade não existe
REACTION_NOT_FOUND "Reação não foi encontrada." Reação ao comentário não existe

Outros Recursos

Código de Erro Mensagem Descrição
FILE_NOT_FOUND "Arquivo não foi encontrado." Anexo de arquivo não existe
SUBSCRIPTION_NOT_FOUND "Assinatura não encontrada." Assinatura de cobrança não existe
INVOICE_NOT_FOUND "Fatura não encontrada." Registro de fatura não existe
CHECKLIST_NOT_FOUND "Checklist não foi encontrado." Checklist não existe
CHECKLIST_ITEM_NOT_FOUND "Item do checklist não foi encontrado." Item do checklist não existe
PROJECT_ROLE_NOT_FOUND "Papel do projeto não foi encontrado." Papel de projeto personalizado não existe
PROJECT_ACCESS_NOT_FOUND "Acesso ao projeto não foi encontrado." Acesso do usuário ao projeto não existe
NOTIFICATION_NOT_FOUND "Notificação não foi encontrada." Notificação não existe
DASHBOARD_NOT_FOUND "Painel não foi encontrado." Painel não existe
KEY_NOT_FOUND "Chave não foi encontrada." Chave de configurações não existe

Erros de Validação

Código de Erro Mensagem Descrição
BAD_USER_INPUT "Entrada inválida." Falha de validação de entrada genérica
VALIDATION_ERROR "Parâmetros inválidos" Parâmetros da solicitação falharam na validação
BAD_EMAIL "Você precisa inserir um e-mail válido." Formato de e-mail inválido
INVALID_IDS "IDs inválidos." Um ou mais IDs na solicitação são inválidos
PHONE_INVALID "Telefone é inválido." Formato de número de telefone inválido
URL_INVALID "URL é inválida." Formato de URL inválido
INVALID_RECURRING_DUE_DATE "Data de vencimento inválida para tarefa recorrente" Validação da data da tarefa recorrente falhou
INVALID_COLOR "Cor inválida" Valor de cor não corresponde ao formato esperado

Erros de Lógica de Negócio

Limites e Quotas

Código de Erro Mensagem Descrição
COMPANY_LIMIT "Você atingiu o limite de empresas para sua conta." Limite máximo de empresas atingido
PROJECT_LIMIT "Você atingiu o limite de projetos para sua empresa." Limite máximo de projetos atingido
USER_LIMIT "Você atingiu o limite de usuários para sua empresa." Limite máximo de usuários atingido
PROJECT_TEMPLATE_LIMIT "Você atingiu o limite de modelos para sua empresa." Limite máximo de modelos atingido
CUSTOM_FIELD_LIMIT "Limite de campos personalizados atingido." Limite máximo de campos personalizados atingido
TODO_LIST_LIMIT "Você atingiu o limite de listas para seu projeto." Limite máximo de listas por projeto
TOO_MANY_TODOS "Tantos todos." Limite de registros excedido
TOO_MANY_OPTIONS "Muitas opções." Limite de opções de campo de seleção excedido
MAX_FILE_SIZE "O tamanho máximo do arquivo é 4,8 GB" Limite de tamanho de upload de arquivo excedido

Conflitos de Recursos

Código de Erro Mensagem Descrição
TAG_ALREADY_EXISTS "Tag já existe." Tag com o mesmo nome existe no projeto
COMPANY_SLUG_ALREADY_EXISTS "Empresa já existe." Slug/URL da empresa já está em uso
USER_ALREADY_EXISTS "Usuário já existe." E-mail do usuário já registrado
ALREADY_INVITED "O usuário já foi convidado." O usuário já tem um convite pendente
USER_ALREADY_IN_PROJECT "Usuário já está neste projeto." O usuário já tem acesso ao projeto
FILE_TYPE_NOT_ALLOWED "Tipo de arquivo não permitido." Tipo de arquivo enviado é restrito

Erros de Permissão e Acesso

Código de Erro Mensagem Descrição
UNABLE_TO_DELETE_ONLY_ADMIN "Não é possível excluir o único Admin na empresa." Não é possível remover o último admin
UNABLE_TO_UPDATE_OWNER "Não é possível atualizar o PROPRIETÁRIO." Não é possível modificar permissões de proprietário
TODO_LIST_IS_HIDDEN "Lista de tarefas está oculta." Lista oculta do papel do usuário
COMPANY_NOT_ACTIVE "Empresa não está ativa." Assinatura da empresa inativa
PROJECT_NOT_ACTIVE "Projeto não está ativo." Projeto está arquivado/inativo

Erros de Integridade de Dados

Código de Erro Mensagem Descrição
UNABLE_TO_DELETE_LIST_WITH_TODOS "Não é possível excluir lista com todos." A lista deve estar vazia para ser excluída
UNABLE_TO_DELTE_FILE "Não é possível excluir arquivo." A exclusão do arquivo falhou (erro de digitação no código)
UNABLE_TO_MOVE_TODO "Não é possível mover todo." Não é possível mover registro entre listas
DEPENDENCY_HAS_DEPENDENCY "Dependência tem dependência" Dependência circular detectada
TODO_DEPENDS_ON_ITSELF "Todo depende de si mesmo" Dependência autorreferencial

Erros de Stripe/Pagamento

Código de Erro Mensagem Descrição
STRIPE_CREATING_CUSTOMER "Erro ao criar cliente no stripe." Falha na criação do cliente no Stripe
STRIPE_ALREADY_SUBSCRIBED "Já inscrito." Assinatura ativa existe
STRIPE_MISSING_PAYMENT_METHOD "Método de pagamento ausente." Nenhum método de pagamento registrado
STRIPE_CREATING_SUBSCRIPTION "Erro ao criar assinatura no stripe." Falha na criação da assinatura
STRIPE_UPDATING_SUBSCRIPTION "Erro ao atualizar assinatura no stripe." Falha na atualização da assinatura
STRIPE_CHECKOUT_SESSION "Erro ao criar sessão de checkout no stripe." Falha na criação da sessão de checkout
STRIPE_CUSTOMER_PORTAL "Erro ao criar portal do cliente no stripe." Falha na criação da sessão do portal
STRIPE_TAX_ID "Não foi possível salvar o ID fiscal" Validação/salvamento do ID fiscal falhou
PAYMENT_REQUIRED "Pagamento necessário." Recurso requer assinatura ativa
NO_PAYMENT_REQUIRED "Nenhum pagamento necessário." Pagamento não é necessário para a operação

Erros de Autenticação e Sessão

Código de Erro Mensagem Descrição
INVALID_CREDENTIALS "Credenciais inválidas." Nome de usuário/senha incorretos
EXPIRED_RESET_TOKEN "Token de redefinição expirou." Token de redefinição de senha expirado
OAUTH_FAILED "Processo OAuth falhou." Autenticação OAuth falhou
SAML_NOT_ENABLED "SSO (SAML) não está habilitado." SSO SAML não configurado
SSO_AUTO_PROVISION_DISABLED "Provisionamento automático está desativado." Não é possível criar usuários SSO automaticamente

Limitação de Taxa

A limitação de taxa é tratada pelo pacote graphql-rate-limit com diferentes configurações:

Tipo de Limite Janela Máx. Solicitações Aplicado a
Standard 60s 500 Most queries/mutations
Sensitive 300s 10 Password reset, auth operations
Expensive 60s 20 Complex queries, bulk operations
Search 60s 60 Search operations
File Upload 60s 100 File upload operations

Quando a taxa é limitada, você receberá um erro padrão do GraphQL com uma mensagem indicando que o limite foi excedido.

Erros do Sistema e Internos

Código de Erro Mensagem Descrição
INTERNAL_SERVER_ERROR "Erro interno do servidor." Erro genérico para erros não seguros em produção
UNKNOWN_ERROR "Erro desconhecido." Ocorreu um erro inesperado
RESOLVER_NOT_FOUND "Resolvedor não encontrado" Resolver GraphQL ausente
FIELD_NOT_IN_SCHEMA "Campo não está no esquema" Campo solicitado não existe

Melhores Práticas para Tratamento de Erros

Tratamento do Lado do Cliente

try {
  const result = await client.mutate({
    mutation: CREATE_TODO,
    variables: { input }
  });
} catch (error) {
  if (error.graphQLErrors?.length > 0) {
    const errorCode = error.graphQLErrors[0].extensions?.code;
    
    switch (errorCode) {
      case 'UNAUTHENTICATED':
        // Redirect to login
        break;
      case 'TODO_NOT_FOUND':
        // Show "Record not found" message
        break;
      case 'VALIDATION_ERROR':
        // Display validation errors
        break;
      default:
        // Show generic error message
    }
  }
}

Cenários Comuns de Erro

  1. Autenticação Requerida: UNAUTHENTICATED - O usuário precisa fazer login
  2. Permissão Negada: FORBIDDEN - O usuário não possui o papel/permissão necessária
  3. Recurso Não Encontrado: *_NOT_FOUND - O recurso não existe ou o usuário não pode acessá-lo
  4. Validação Falhou: VALIDATION_ERROR, BAD_USER_INPUT - Verifique os parâmetros de entrada
  5. Limite de Taxa: Verifique os cabeçalhos de limite de taxa e implemente um retrocesso
  6. Pagamento Necessário: PAYMENT_REQUIRED - O recurso requer uma assinatura

Documentação Relacionada

© Blue | Projetado com ❤ através do

Assistente de IA

As respostas são geradas usando IA e podem conter erros.

Como posso ajudá-lo?

Pergunte-me qualquer coisa sobre o Blue ou esta documentação.

Digite para enviar • Shift+Enter para nova linha • ⌘I para abrir