Tratamento de Erros

Este tópico vai te ajudar a lidar com os diferentes tipos de erros que a API pode retornar.

Erros da API

Os erros retornados pela nossa API seguem o seguinte padrão:

{
  "code": "UNKNOWN_ERROR",
  "message": "Essa é a mensagem retornada pelo erro",
  "status_code": 400,
  "timestamp": "2024-08-06T13:13:22.139Z",
  "path": "/api/v1/error-path",
  "handled": true,
  "errors": [
    "Nesta lista você encontrará possíveis erros de validação",
    "Podem haver mais de um"
  ]
}

Lista de códigos de erro que podem ocorrer:

Código	Motivo
UNKNOWN_ERROR	O erro ocorrido não se enquadra em nenhum outro código, mas o motivo estará detalhado na mensagem retornada.
INTERNAL_SERVER_ERROR	Ocorreu um erro interno no sistema. Caso a mensagem não seja clara, solicite auxílio do suporte.
VALIDATION_ERROR	Os dados enviados não passaram na validação. Os erros estão listados no campo errors.
INVALID_TOKEN	O token de autenticação enviado não é válido. Pode ter ocorrido um erro na sua integração.
SESSION_EXPIRED	A sessão do usuário expirou. Realize um novo login.
FEATURE_FLAG_DISABLED	A funcionalidade que você está tentando acessar está desativada. A mensagem detalhará os motivos.
PERMISSION_DENIED	Você não tem permissão para acessar o recurso solicitado. Se necessário, entre em contato com o suporte.
INCORRECT_PASSWORD	A senha informada é inválida. Esse erro ocorre apenas em requisições que exigem confirmação de senha.

Leia o documento "Feature Flags" para entender mais sobre o erro FEATURE_FLAG_DISABLED.

Outros códigos de erro podem ser criados, mas nunca removidos. Portanto, evite validações estritas baseadas apenas nos códigos acima.

Erros da Cloudflare

Utilizamos os serviços da Cloudflare como camada de segurança. Em alguns casos, você pode receber erros desse serviço, sobre os quais não temos controle. Você pode identificar os erros da Cloudflare através do header server, que sempre retornará o valor cloudflare, e do StatusCode.

Lista de possiveis erro da Cloudflare:

StatusCode	Motivo
429	Você fez múltiplas requisições em um curto período e foi limitado. Aguarde para continuar usando o serviço.
403	Seu acesso foi bloqueado por diversos motivos, como país de origem, IP suspeito, entre outros. Entre em contato com o suporte para mais informações.

Leia o documento "Limites de Uso" para entender mais sobre o erro com StatusCode 429.

Podem ocorrer outros erros que não estão listados acima. Por isso, sempre trate possíveis exceções.

---

Exemplo tratameto de erro

Abaixo está um exemplo em TypeScript de como tratar os possíveis erros que podem ocorrer em nossa API.

import { AxiosError } from 'axios';

const handlePontoDigitalError = (
  error: Error | AxiosError | unknown,
): string | string[] => {
  // Trata erros internos do código
  if (error instanceof Error) {
    return error?.message || 'Erro desconhecido!';
  }

  // Trata erros da resposta da API
  if (error instanceof AxiosError) {
    const errorResponse = error?.response;
    const isCloudflareError = errorResponse?.headers?.Server === 'cloudflare';

    if (isCloudflareError) {
      switch (errorResponse?.status) {
        case 429:
          return 'Você fez muitas requisições em um curto período! Por favor, aguarde antes de tentar novamente.';
        default:
          return 'Oops! Ocorreu algum erro durante a conexão com nossos serviços parceiros. Por favor, entre em contato com o suporte.';
      }
    }

    const errorData: ErrorResponseData = errorResponse?.data;

    switch (errorData?.code) {
      case 'VALIDATION_ERROR':
        return errorData?.errors || errorData?.message || 'Não foi possível identificar o motivo do erro!';
      default:
        return errorData?.message || 'Não foi possível identificar o motivo do erro!';
    }
  }

  // Fallback em caso de falha ao identificar o erro
  return 'Um erro desconhecido ocorreu!';
};

export type ErrorResponseData = {
  code?: string;
  message?: string;
  status_code?: number;
  timestamp?: string;
  path?: string;
  handled?: boolean;
  errors?: string[];
};

---

Em caso de problemas ou dúvidas entre em contato com o [email protected].