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

# Erros

> Códigos HTTP e formato de erro retornado pela API

A API segue convenções HTTP padrão. Em caso de erro, você recebe um objeto JSON com os campos `statusCode`, `message` e `error`.

## Códigos comuns

| Status                      | Quando acontece                                                                              |
| --------------------------- | -------------------------------------------------------------------------------------------- |
| `400 Bad Request`           | Falha de validação do payload (ex: campo obrigatório faltando, formato inválido)             |
| `401 Unauthorized`          | Headers `client-id`/`client-secret` ausentes ou inválidos                                    |
| `403 Forbidden`             | Produto necessário não habilitado (ex.: `tokenization` em tokenização de cartão)             |
| `404 Not Found`             | Subconta não encontrada para o `internalId` informado                                        |
| `409 Conflict`              | `x-idempotency-key` reutilizada com payload diferente, ou estado alterado por outro processo |
| `422 Unprocessable Entity`  | Operação recusada pelo provedor (ex.: cartão não provisionado na tokenização)                |
| `429 Too Many Requests`     | Rate limit excedido (5/min em subcontas; 30/min em tokenização)                              |
| `500 Internal Server Error` | Erro inesperado no servidor; tentar novamente após alguns segundos                           |

## Formato do erro

```json theme={null}
{
  "statusCode": 400,
  "message": [
    "documentNumber deve conter apenas números"
  ],
  "error": "Bad Request"
}
```

O campo `message` pode vir como string única ou array de mensagens (no caso de validações do `class-validator`).

## Boas práticas

* Sempre **logue** o `statusCode` e `message` retornados para debug.
* Em **429**, aplique backoff exponencial antes de tentar novamente.
* Em **5xx**, reenvie a mesma `x-idempotency-key` para evitar duplicação quando o servidor voltar.
* Em **409 de idempotência**, **não retry** - revise o payload, gere uma nova chave se for uma operação nova.