Erros

Hierarquia de erros

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

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

Tipos de erro

`SoarLabzError`

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

import { SoarLabzError } from '@soarlabz/security-sdk';

try {
  await client.tokenizer.tokenize({ ... });
} catch (error) {
  if (error instanceof SoarLabzError) {
    // 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 '@soarlabz/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 '@soarlabz/security-sdk';

try {
  await client.tokenizer.tokenize({ ... });
} catch (error) {
  if (error instanceof ValidationError) {
    console.error

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 SoarLabz (status HTTP diferente de 2xx, exceto 401).

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

try {
  await client.tokenizer.tokenize({ ... });
} catch (error) {
  if (error instanceof ApiError) {
    console.error

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 '@soarlabz/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 '@soarlabz/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 '@soarlabz/security-sdk';

try {
  await client.threeds.authenticate({ ... });
} catch (error) {
  if (error instanceof ThreeDSError) {
    console.error

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,
  SoarLabzError,
  AuthenticationError,
  ValidationError,
  ApiError,
  NetworkError,
  TimeoutError,
  ThreeDSError,
} from '@soarlabz/security-sdk';

try {
  const client = new

Hierarquia de erros

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

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

Tipos de erro

`SoarLabzError`

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

import { SoarLabzError } from '@soarlabz/security-sdk';

try {
  await client.tokenizer.tokenize({ ... });
} catch (error) {
  if (error instanceof SoarLabzError) {
    // 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 '@soarlabz/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 '@soarlabz/security-sdk';

try {
  await client.tokenizer.tokenize({ ... });
} catch (error) {
  if (error instanceof ValidationError) {
    console.error

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 SoarLabz (status HTTP diferente de 2xx, exceto 401).

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

try {
  await client.tokenizer.tokenize({ ... });
} catch (error) {
  if (error instanceof ApiError) {
    console.error

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 '@soarlabz/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 '@soarlabz/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 '@soarlabz/security-sdk';

try {
  await client.threeds.authenticate({ ... });
} catch (error) {
  if (error instanceof ThreeDSError) {
    console.error

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

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,
  SoarLabzError,
  AuthenticationError,
  ValidationError,
  ApiError,
  NetworkError,
  TimeoutError,
  ThreeDSError,
} from '@soarlabz/security-sdk';

try {
  const client = new

Hierarquia de erros

Tipos de erro

`SoarLabzError`

`AuthenticationError`

`ValidationError`

`ApiError`

`NetworkError`

`TimeoutError`

`ThreeDSError`

Retries automáticos

Exemplo completo

On this page

Erros

Hierarquia de erros

Tipos de erro

`SoarLabzError`

`AuthenticationError`

`ValidationError`

`ApiError`

`NetworkError`

`TimeoutError`

`ThreeDSError`

Retries automáticos

Exemplo completo

On this page