# 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:

```json
{
  "id": "69e0fbc96642f8aefc9ddb75",
  "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:

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

{% hint style="info" %}
Leia o documento "Feature Flags" para entender mais sobre o erro `FEATURE_FLAG_DISABLED`.
{% endhint %}

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:

<table><thead><tr><th width="126.00006103515625">StatusCode</th><th>Motivo</th></tr></thead><tbody><tr><td>429</td><td>Você fez múltiplas requisições em um curto período e foi limitado. Aguarde para continuar usando o serviço.</td></tr><tr><td>403</td><td>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.</td></tr></tbody></table>

{% hint style="info" %}
Leia o documento Limites de Uso para entender mais sobre o erro com StatusCode `429`.
{% endhint %}

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.

```typescript
import { AxiosError } from 'axios';

const handleAltPayError = (
  error: Error | AxiosError | unknown,
): string | string[] => {
  if (error?.statusCode === 429) {
    return "Você fez muitas requisições em um curto período! Por favor, aguarde antes de tentar novamente.";
  }

  return error?.data?.errors?.length
    ? error?.data?.errors
    : error?.data?.message ||
        error?.message ||
        "Não foi possível identificar o motivo do erro!";
};
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.altpaybr.com.br/documentation/api-operation/interactive-blocks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.