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

# Erros e códigos HTTP

> Envelope de erro da API v1, status comuns e boas práticas

Rotas sob `/v1/*` retornam erros em JSON padronizado. Rotas de dashboard e autenticação podem usar formato NestJS clássico (`statusCode`, `message`).

## Envelope de erro (API pública)

```json theme={null}
{
  "success": false,
  "message": "Mensagem legível para integração",
  "error": {
    "code": "Bad Request",
    "statusCode": 400
  },
  "requestId": "req_7f3a2b1c"
}
```

| Campo              | Descrição                                                                                       |
| ------------------ | ----------------------------------------------------------------------------------------------- |
| `message`          | Texto principal (pode repetir detalhe de validação)                                             |
| `error.code`       | Nome da exceção HTTP (ex.: `Bad Request`, `Unauthorized`, `Forbidden`, `Not Found`, `Conflict`) |
| `error.statusCode` | Código HTTP numérico                                                                            |
| `requestId`        | Identificador para suporte                                                                      |

<Note>
  Não existe enum fixa `BAD_REQUEST` no campo `code`. Use `error.statusCode` e `message` na lógica do integrador.
</Note>

## Status HTTP frequentes

| Status | Situação típica                                                  |
| ------ | ---------------------------------------------------------------- |
| `400`  | Body inválido, regra de negócio (saldo, trilho, limites)         |
| `401`  | Chave ausente, revogada ou inválida                              |
| `403`  | Chave sem permissão na rota; trilho indisponível; conta suspensa |
| `404`  | Recurso não encontrado ou de outra conta                         |
| `409`  | Conflito de unicidade (ex.: `externalReference` duplicado)       |
| `429`  | Rate limit excedido                                              |
| `500`  | Erro interno (retente com backoff; abra ticket com `requestId`)  |

## Códigos de domínio (trilho)

Respostas `403` ou `409` podem incluir mensagens relacionadas a:

| Código lógico                | Significado                         |
| ---------------------------- | ----------------------------------- |
| `RAIL_UNAVAILABLE`           | Trilho não habilitado na conta      |
| `RAIL_ACCESS_REVOKED`        | Acesso ao trilho revogado           |
| `RAIL_OPERATION_NOT_ALLOWED` | Operação não permitida neste trilho |
| `RAIL_REQUIRED`              | Operação exige trilho específico    |

## Validação de body

Campos inválidos retornam `400` com mensagem agregada. Exemplos:

* `amount` abaixo do mínimo da operação
* `description` com menos de 3 caracteres
* `splitUser` sem `splitTax` (ou vice-versa)
* `pixKey` ausente quando não há `pixCopyPaste`

## Prisma e conflitos

Violação de unicidade no banco (`P2002`) mapeia para `409 Conflict`.

## Rate limiting

`429` com corpo simplificado. Veja [Rate limiting](/api-reference/rate-limiting).

## Boas práticas

<Tip>
  Registre sempre `requestId` nos logs do seu servidor ao tratar erros `5xx`.
</Tip>

<Tip>
  Não interprete mensagens em português como API estável: prefira `statusCode` e campos estruturados em `data` nas respostas de sucesso.
</Tip>

<Warning>
  Em webhooks inbound para **seu** servidor, valide assinatura antes de processar. Erros de parsing devem retornar `4xx` apenas quando o payload for inválido; duplicatas devem retornar `200`.
</Warning>