> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.gomoney.me/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.gomoney.me/_mcp/server.

# Modelos de Erro

## Visão geral

Os erros do ecossistema GoMoney aparecem em dois formatos principais:

* respostas da plataforma, usadas em customers e validações correlatas;
* respostas da camada PIX, usadas em autenticação PIX e cobranças.

## Erro de autenticação da API PIX

Usado em cenários como credenciais inválidas no login da API PIX.

```json
{
  "statusCode": 401,
  "timestamp": 1783188000000,
  "path": "/auth/login",
  "message": "Invalid user or password."
}
```

| Campo        | Tipo      | Descrição              |
| ------------ | --------- | ---------------------- |
| `statusCode` | `integer` | Código HTTP retornado. |
| `timestamp`  | `integer` | Momento da falha.      |
| `path`       | `string`  | Caminho chamado.       |
| `message`    | `string`  | Mensagem de erro.      |

## Erro genérico de autenticação

Usado quando a sessão ou a credencial de integração não são aceitas.

```json
{
  "statusCode": 401,
  "message": "Invalid API access key"
}
```

| Campo        | Tipo      | Descrição                    |
| ------------ | --------- | ---------------------------- |
| `statusCode` | `integer` | Código HTTP retornado.       |
| `message`    | `string`  | Motivo resumido da rejeição. |

## Erro de validação

Usado quando o corpo enviado não respeita o contrato da operação.

```json
{
  "statusCode": 400,
  "message": [
    "email must be an email"
  ],
  "error": "Bad Request"
}
```

| Campo        | Tipo                   | Descrição                             |
| ------------ | ---------------------- | ------------------------------------- |
| `statusCode` | `integer`              | Código HTTP retornado.                |
| `message`    | `string` ou `string[]` | Detalhes das validações que falharam. |
| `error`      | `string`               | Categoria geral do erro.              |

## Erro de negócio da plataforma

Usado quando o recurso existe, mas o usuário não pode operá-lo, ou quando o recurso não foi encontrado.

```json
{
  "statusCode": 403,
  "message": "You do not have access to this customer"
}
```

```json
{
  "statusCode": 404,
  "message": "Customer not found"
}
```

## Erro da camada PIX

Usado quando a camada PIX retorna um código interno específico do fluxo.

```json
{
  "statusCode": 400,
  "path": "/pix/create/brl",
  "code": "ERR13",
  "message": "Payer > Document Number is not a valid CNPJ or CPF"
}
```

| Campo        | Tipo      | Descrição                    |
| ------------ | --------- | ---------------------------- |
| `statusCode` | `integer` | Código HTTP retornado.       |
| `path`       | `string`  | Caminho chamado.             |
| `code`       | `string`  | Código interno do fluxo PIX. |
| `message`    | `string`  | Descrição da falha.          |

## Mapeamento prático por cenário

| Cenário                                        | Código mais comum | Interpretação                                     |
| ---------------------------------------------- | ----------------- | ------------------------------------------------- |
| Login da API PIX com credenciais inválidas     | `401`             | Usuário ou senha incorretos.                      |
| Login PIX bloqueado por excesso de tentativas  | `429`             | Conta temporariamente bloqueada.                  |
| Customer criado com corpo inválido             | `400`             | Falha de validação de dados.                      |
| Customer acessado por outra conta              | `403`             | Recurso sem vínculo com o usuário autenticado.    |
| Customer inexistente                           | `404`             | Identificador não encontrado.                     |
| Cobrança PIX com documento inválido            | `400`             | Dado do pagador fora do formato esperado.         |
| Cobrança PIX fora da janela permitida para GMC | `503`             | Restrição operacional temporária.                 |
| Cobrança PIX inexistente ou sem vínculo        | `417`             | Cobrança não localizada para a conta autenticada. |

## Como tratar no integrador

* registrar o código HTTP e, quando existir, o código interno do fluxo PIX;
* armazenar o caminho chamado e o identificador operacional da transação;
* evitar retentativas automáticas para erros de autenticação e validação;
* usar retentativa controlada apenas em indisponibilidades transitórias.