Tratamento de Erros

Aprenda a identificar e tratar erros retornados pela API ActivePayments para criar integrações robustas e com boa experiência para o usuário.

Estrutura de Erro

Quando ocorre um erro, a API retorna um JSON com a seguinte estrutura:

Resposta de Erro (400 Bad Request)
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Dados inválidos na requisição",
    "details": [
      {
        "field": "amount",
        "message": "Valor mínimo é R$ 1,00"
      },
      {
        "field": "customerCpf",
        "message": "CPF inválido"
      }
    ]
  },
  "statusCode": 400,
  "timestamp": "2024-01-15T10:00:00.000Z"
}

Campos da Resposta de Erro

Campo	Tipo	Descrição
`success`	boolean	Sempre `false` em caso de erro
`error.code`	string	Código único do erro (use para tratamento programático)
`error.message`	string	Mensagem legível para humanos (pode exibir ao usuário)
`error.details`	array	Lista de erros de validação por campo (opcional)
`statusCode`	number	Código HTTP da resposta

Códigos HTTP

Código	Significado	Quando Ocorre
`200`	OK	Requisição bem-sucedida (GET)
`201`	Created	Recurso criado com sucesso (POST)
`400`	Bad Request	Dados inválidos ou faltando campos obrigatórios
`401`	Unauthorized	API Key inválida, expirada ou IP não autorizado
`403`	Forbidden	Sem permissão para acessar este recurso
`404`	Not Found	Recurso não encontrado (cobrança, transação)
`429`	Too Many Requests	Rate limit excedido
`500`	Internal Server Error	Erro interno - contate o suporte

Códigos de Erro Comuns

Erros de Validação (400)

Código	Descrição	Solução
`VALIDATION_ERROR`	Campos com dados inválidos	Verifique o array `details` para erros específicos
`INVALID_CPF`	CPF com formato ou dígitos inválidos	Envie apenas números (11 dígitos) sem pontuação
`INVALID_AMOUNT`	Valor fora do range permitido	Valor deve ser entre R$ 1,00 e R$ 100.000,00

Erros de Autenticação (401)

Erro de Autenticação
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "API Key inválida ou expirada"
  },
  "statusCode": 401,
  "timestamp": "2024-01-15T10:00:00.000Z"
}

Código	Causa
`UNAUTHORIZED`	API Key não existe ou secret incorreto
`API_KEY_EXPIRED`	API Key passou da data de expiração
`API_KEY_REVOKED`	API Key foi revogada no Dashboard
`IP_NOT_ALLOWED`	IP de origem não está na whitelist

Erro de Recurso Não Encontrado (404)

Erro 404
{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Cobrança não encontrada"
  },
  "statusCode": 404,
  "timestamp": "2024-01-15T10:00:00.000Z"
}

Rate Limit (429)

Rate Limit Excedido
{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Limite de requisições excedido. Tente novamente em 60 segundos.",
    "retryAfter": 60
  },
  "statusCode": 429,
  "timestamp": "2024-01-15T10:00:00.000Z"
}

Limite de RequisiçõesA API permite 100 requisições por minuto por API Key. Ao exceder, aguarde o tempo indicado em retryAfter.

Exemplo de Tratamento

Recomendamos implementar um handler centralizado para tratar os diferentes tipos de erro:

Node.js - Tratamento de Erros
async function createCharge(data) {
  try {
    const response = await fetch('https://api.ActivePayments.com.br/api/v1/charges', {
      method: 'POST',
      headers: {
        'Authorization': `ApiKey ${publicKey}:${secret}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(data),
    });

    const result = await response.json();

    if (!result.success) {
      // Tratar erro baseado no código
      switch (result.error.code) {
        case 'VALIDATION_ERROR':
          // Mostrar erros de validação para o usuário
          result.error.details?.forEach(err => {
            console.error(`Campo ${err.field}: ${err.message}`);
          });
          break;
        
        case 'UNAUTHORIZED':
          // Verificar credenciais ou renovar API Key
          console.error('Credenciais inválidas');
          break;
        
        case 'RATE_LIMIT_EXCEEDED':
          // Aguardar e tentar novamente
          const retryAfter = result.error.retryAfter || 60;
          await new Promise(r => setTimeout(r, retryAfter * 1000));
          return createCharge(data); // Retry
          
        default:
          console.error(result.error.message);
      }
      
      throw new Error(result.error.message);
    }

    return result.data;
  } catch (error) {
    console.error('Erro na requisição:', error);
    throw error;
  }
}

Boas Práticas

Use o campo code para lógica de tratamento, não o message (que pode mudar)
Implemente retry com backoff exponencial para erros 429 e 5xx
Registre logs detalhados incluindo o corpo completo do erro
Mostre mensagens amigáveis ao usuário final, não detalhes técnicos
Valide dados localmente antes de enviar à API para reduzir erros

Próximo passoVeja como configurar Webhooks para receber notificações.