Códigos de Erro

Referência completa de códigos de erro da API Nexus com descrições e soluções.

Códigos HTTP

Código Status Descrição
200 OK Requisição processada com sucesso
201 Created Recurso criado com sucesso
400 Bad Request Parâmetros inválidos ou ausentes
401 Unauthorized Autenticação ausente ou inválida
402 Payment Required Saldo insuficiente
403 Forbidden Sem permissão para acessar recurso
404 Not Found Recurso não encontrado
409 Conflict Conflito com recurso existente
500 Internal Server Error Erro interno do servidor

Erros de Autenticação

Código Mensagem Solução
MISSING_API_KEY API Key não fornecida Adicione o header X-API-KEY à requisição
INVALID_API_KEY API Key inválida Verifique se a chave está correta e ativa
INVALID_CREDENTIALS Credenciais inválidas Verifique email e senha

Exemplo de Erro de Autenticação

{
  "error": "API Key não fornecida",
  "code": "MISSING_API_KEY",
  "statusCode": 401
}

Erros de Validação

Código Mensagem Solução
MISSING_FIELDS Campos obrigatórios ausentes Verifique todos os parâmetros requeridos
INVALID_PHONE_NUMBER Número de telefone inválido Use formato com código do país (ex: 5511999999999)
INVALID_ROUTE_ID ID da rota inválido Use um routeId válido da sua conta
INVALID_JSON JSON mal formatado Verifique a sintaxe do JSON no body
MESSAGE_TOO_LONG Mensagem excede limite SMS: máx 160 caracteres, RCS: máx 3000

Exemplo de Erro de Validação

{
  "error": "Campos obrigatórios ausentes",
  "code": "MISSING_FIELDS",
  "details": {
    "missing": ["to", "message"]
  },
  "statusCode": 400
}

Erros de Negócio

Código Mensagem Solução
INSUFFICIENT_BALANCE Saldo insuficiente Adicione créditos à sua conta
NO_ROUTES_AVAILABLE Nenhuma rota disponível Entre em contato com suporte
CAMPAIGN_NOT_FOUND Campanha não encontrada Verifique o ID da campanha
RATE_LIMIT_EXCEEDED Limite de taxa excedido Aguarde antes de fazer nova requisição
ACCOUNT_NOT_VERIFIED Conta não verificada Verifique seu email/telefone

Exemplo de Erro de Negócio

{
  "error": "Saldo insuficiente para envio",
  "code": "INSUFFICIENT_BALANCE",
  "details": {
    "required": 50.00,
    "available": 25.50,
    "currency": "BRL"
  },
  "statusCode": 402
}

Tratamento de Erros

Estrutura Padrão de Erro

Todas as respostas de erro seguem o mesmo formato:

{
  "error": "Descrição legível do erro",
  "code": "ERROR_CODE_CONSTANT",
  "details": {
    "...": "informações adicionais"
  },
  "statusCode": 400
}

Exemplo de Implementação (JavaScript)

async function sendMessage(data) {
  try {
    const response = await fetch(API_URL + '/send', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-API-KEY': API_KEY
      },
      body: JSON.stringify(data)
    });

    const result = await response.json();

    if (!response.ok) {
      switch (result.code) {
        case 'INSUFFICIENT_BALANCE':
          alert('Saldo insuficiente. Adicione créditos.');
          break;
        case 'INVALID_PHONE_NUMBER':
          alert('Número de telefone inválido.');
          break;
        default:
          alert('Erro: ' + result.error);
      }
      throw new Error(result.error);
    }

    return result;
  } catch (error) {
    console.error('Erro ao enviar mensagem:', error);
    throw error;
  }
}

Boas Práticas

  • Sempre verifique o status HTTP antes de processar resposta
  • Implemente retry com backoff exponencial para erros 5xx
  • Log todos os erros para debugging
  • Trate erros específicos com mensagens claras ao usuário
  • Configure alertas para erros críticos (saldo baixo, falhas de rota)
  • Nunca exponha detalhes técnicos de erro ao usuário final
Dica: Use o campo code (não a mensagem) para tratamento programático de erros, pois as mensagens podem mudar.

Precisa de Ajuda?

Se você continuar encontrando erros não documentados, entre em contato: