Erros

Hierarquia de erros

Todos os erros do SDK estendem AccithusError, que por sua vez estende o Error nativo do JavaScript. Isso permite usar instanceof para identificar erros específicos:

Error
└── AccithusError
    ├── AuthenticationError
    ├── ValidationError
    ├── ApiError
    ├── NetworkError
    ├── TimeoutError
    └── ThreeDSError

Tipos de erro

`AccithusError`

Classe base de todos os erros do SDK. Use para capturar qualquer erro da biblioteca.

import { AccithusError } from '@accithus/security-sdk';

try {
  await client.tokenizer.tokenize({ ... });
} catch (error) {
  if (error instanceof AccithusError) {
    // Qualquer erro do SDK
  }
}

Propriedade	Tipo	Descrição
`name`	`string`	Nome da classe do erro.
`message`	`string`	Mensagem descritiva.

`AuthenticationError`

A chave pública é inválida, inativa ou não foi encontrada.

import { AuthenticationError } from '@accithus/security-sdk';

Propriedade	Tipo	Valor
`name`	`string`	`'AuthenticationError'`
`message`	`string`	`'Invalid public key'`

Causas comuns:

Chave pública incorreta ou com typo
Chave revogada ou inativa

`ValidationError`

Dados de entrada inválidos. Lançado antes de fazer qualquer requisição à API.

import { ValidationError } from '@accithus/security-sdk';

try {
  await client.tokenizer.tokenize({ ... });
} catch (error) {
  if (error instanceof ValidationError) {
    console.error(`Campo: ${error.field}`, error.message);
  }
}

Propriedade	Tipo	Descrição
`name`	`string`	`'ValidationError'`
`message`	`string`	Descrição do erro de validação.
`field`	`string`	Nome do campo inválido (ex: `card.number`, `card.cvv`).

Validações na inicialização:

Campo	Regra
`publicKey`	Obrigatório, string, prefixo `pk_`, mínimo 10 caracteres.
`timeout`	Se fornecido, entre 1.000 e 60.000 ms.

Validações na tokenização:

Campo	Regra
`card.number`	Mínimo 13 dígitos.
`card.cvv`	Mínimo 3 dígitos.
`card.holderName`	Não pode ser vazio.
`card.expirationMonth`	Obrigatório.
`card.expirationYear`	Obrigatório.

`ApiError`

Erro retornado pela API da Accithus (status HTTP diferente de 2xx, exceto 401).

import { ApiError } from '@accithus/security-sdk';

try {
  await client.tokenizer.tokenize({ ... });
} catch (error) {
  if (error instanceof ApiError) {
    console.error(`Status: ${error.status}`, `Code: ${error.code}`, error.message);
  }
}

Propriedade	Tipo	Descrição
`name`	`string`	`'ApiError'`
`message`	`string`	Mensagem descritiva (em português).
`status`	`number`	Código HTTP (400, 404, 422, 500 etc.).
`code`	`string`	Código do erro em inglês (ex: `TOKENIZE_FAILED`, `SESSION_EXPIRED`).

`NetworkError`

Falha na comunicação com a API (sem resposta do servidor).

import { NetworkError } from '@accithus/security-sdk';

Propriedade	Tipo	Descrição
`name`	`string`	`'NetworkError'`
`message`	`string`	Descrição da falha de rede.

Causas comuns:

Sem conexão com a internet
DNS não resolvido
Firewall bloqueando a requisição
Servidor temporariamente indisponível

`TimeoutError`

A requisição excedeu o tempo limite configurado.

import { TimeoutError } from '@accithus/security-sdk';

Propriedade	Tipo	Descrição
`name`	`string`	`'TimeoutError'`
`message`	`string`	Descrição do timeout.

O timeout padrão é 30 segundos para requisições HTTP e 120 segundos para o fluxo 3DS completo.

`ThreeDSError`

Erro específico do fluxo de autenticação 3D Secure.

import { ThreeDSError } from '@accithus/security-sdk';

try {
  await client.threeds.authenticate({ ... });
} catch (error) {
  if (error instanceof ThreeDSError) {
    console.error(`Status 3DS: ${error.status}`, error.message);
  }
}

Propriedade	Tipo	Descrição
`name`	`string`	`'ThreeDSError'`
`message`	`string`	Descrição do erro.
`status`	`string`	Status do 3DS (`failed`, `error`, `cancelled`).

ThreeDSError é lançado apenas para falhas técnicas no fluxo. Os status unenrolled e failed são retornados normalmente no ThreeDSResult, não como exceção. Consulte a tabela de status em Autenticação 3DS.

Retries automáticos

O SDK implementa retries automáticos com backoff exponencial para erros de servidor (5xx):

Tentativa	Espera
1	Imediata
2	~1.000ms
3	~2.000ms
4	~4.000ms

Erros 4xx (validação, autenticação, não encontrado) não são retentados — são erros definitivos que requerem correção.

Exemplo completo

import {
  Client,
  AccithusError,
  AuthenticationError,
  ValidationError,
  ApiError,
  NetworkError,
  TimeoutError,
  ThreeDSError,
} from '@accithus/security-sdk';

try {
  const client = new Client({ publicKey: 'pk_...' });
  await client.initialize();
  // ... operações do SDK
} catch (error) {
  if (!(error instanceof AccithusError)) {
    // Erro fora do SDK
    throw error;
  }

  switch (error.constructor) {
    case AuthenticationError:
      // Configuração inválida — contate suporte
      break;
    case ValidationError:
      // Corrija os dados do formulário
      break;
    case NetworkError:
    case TimeoutError:
      // Problema de conectividade — tente novamente
      break;
    case ThreeDSError:
      // Falha no 3DS — ofereça alternativa
      break;
    case ApiError:
      // Erro da API — exiba mensagem ao usuário
      break;
  }
}

Começando

Cobranças

Submerchants

Financeiro

Configuração

SDK de Segurança

Webhooks

Hierarquia de erros

Tipos de erro

`AccithusError`

`AuthenticationError`

`ValidationError`

`ApiError`

`NetworkError`

`TimeoutError`

`ThreeDSError`

Retries automáticos

Exemplo completo

​Hierarquia de erros

​Tipos de erro

​AccithusError

​AuthenticationError

​ValidationError

​ApiError

​NetworkError

​TimeoutError

​ThreeDSError

​Retries automáticos

​Exemplo completo

Hierarquia de erros

Tipos de erro

`AccithusError`

`AuthenticationError`

`ValidationError`

`ApiError`

`NetworkError`

`TimeoutError`

`ThreeDSError`

Retries automáticos

Exemplo completo