> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thalpay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Erros

> Codigos de erro e como trata-los

## Formato de erro

Todas as respostas de erro seguem o mesmo formato:

```json theme={null}
{
  "statusCode": 400,
  "message": "Descricao do erro",
  "error": "Bad Request"
}
```

Para erros de validacao, o campo `message` pode ser um array:

```json theme={null}
{
  "statusCode": 400,
  "message": [
    "amount must not be less than 100",
    "customer.email must be an email"
  ],
  "error": "Bad Request"
}
```

## Codigos HTTP

| Status | Significado              | Acao recomendada                                  |
| ------ | ------------------------ | ------------------------------------------------- |
| `200`  | Sucesso                  | -                                                 |
| `201`  | Criado com sucesso       | -                                                 |
| `400`  | Dados invalidos          | Corrija os campos indicados no `message`          |
| `401`  | Nao autenticado          | Verifique sua API Key ou renove o token JWT       |
| `403`  | Sem permissao            | Verifique se a key tem acesso ao recurso          |
| `404`  | Nao encontrado           | Verifique o ID enviado                            |
| `409`  | Conflito de idempotencia | A Idempotency-Key ja foi usada com body diferente |
| `422`  | Entidade nao processavel | Dados validos mas regra de negocio impede a acao  |
| `429`  | Rate limit excedido      | Aguarde o tempo indicado no header `Retry-After`  |
| `500`  | Erro interno             | Tente novamente. Se persistir, contate o suporte  |

## Erros comuns

<AccordionGroup>
  <Accordion title="Idempotency-Key header is required">
    Os endpoints `POST /transactions` e `POST /withdrawals` exigem o header `Idempotency-Key` com um UUID v4 unico.
  </Accordion>

  <Accordion title="amount must not be less than 100">
    O valor minimo de uma transacao e R\$ 1,00 (100 centavos). Lembre que todos os valores sao em centavos.
  </Accordion>

  <Accordion title="Insufficient balance">
    O saldo disponivel na wallet e insuficiente para o saque solicitado. Consulte `GET /seller-wallet/gestao`.
  </Accordion>

  <Accordion title="Seller is not active">
    Sua conta precisa estar com status ACTIVE. Verifique se a documentacao foi aprovada no dashboard.
  </Accordion>

  <Accordion title="Transaction not found">
    O ID informado nao existe ou pertence a outro seller. Cada seller so acessa suas proprias transacoes.
  </Accordion>
</AccordionGroup>

## Tratamento recomendado

```javascript theme={null}
async function callThalpay(endpoint, data) {
  const response = await fetch(`https://api.thalbank.com${endpoint}`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": process.env.THALPAY_API_KEY,
      "Idempotency-Key": crypto.randomUUID(),
    },
    body: JSON.stringify(data),
  });

  if (!response.ok) {
    const error = await response.json();

    switch (response.status) {
      case 401:
        // Renovar token ou verificar API Key
        break;
      case 429:
        // Aguardar Retry-After e tentar novamente
        const retryAfter = response.headers.get("Retry-After");
        await sleep(Number(retryAfter) * 1000);
        return callThalpay(endpoint, data);
      case 400:
      case 422:
        // Erro de validacao — nao adianta retry
        throw new ValidationError(error.message);
      default:
        // Erro inesperado — retry com backoff
        throw new ApiError(error);
    }
  }

  return response.json();
}
```