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

# Erros

> O envelope de erro, o catálogo de códigos e quando repetir a chamada.

Todo erro da API usa o mesmo envelope, com um texto fixo por `code`:

```json theme={null}
{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Dados inválidos. Veja os detalhes.",
    "request_id": "req-rest",
    "details": [
      { "field": "customer.cpf", "reason": "INVALID_CHECK_DIGIT" },
      { "field": "customer.name", "reason": "OUT_OF_RANGE" }
    ]
  }
}
```

| Campo | Quando vem | Conteúdo |
| - | - | - |
| `code` | Sempre | O código do erro. Programe contra ele |
| `message` | Sempre | Texto fixo em português para cada `code`. Pode mudar de redação: não programe contra ele |
| `request_id` | Sempre | O mesmo valor do header `X-Request-Id`. Informe-o ao suporte |
| `details` | Quando o erro aponta campos | Lista de `{ "field", "reason" }`. `field` é o caminho com pontos, por exemplo `customer.address.zip_code` |
| `retry_after` | Só em `CPF_DAILY_LIMIT_REACHED` | A próxima meia-noite de São Paulo, em RFC 3339 |

## Catálogo

| HTTP | `code` | Quando | O que fazer |
| - | - | - | - |
| 400 | `INVALID_REQUEST` | JSON malformado, tipo errado (por exemplo `amount` como número), campo desconhecido ou duplicado, `Content-Type` diferente de `application/json`, id que não é UUID | Corrija a requisição antes de repetir |
| 401 | `UNAUTHENTICATED` | Chave ausente, malformada, inválida ou revogada | Confira a chave |
| 403 | `HUB_INACTIVE` | Hub desativado | Não repita |
| 403 (sem envelope) | | IP fora da allowlist de entrada, bloqueado na camada de gateway/WAF | Fale com o time de integrações |
| 404 | `REFERRAL_NOT_FOUND` | Processo inexistente ou pertencente a outro parceiro | Confira o id |
| 413 | `PAYLOAD_TOO_LARGE` | Corpo acima de 16 KB | Reduza o corpo |
| 422 | `VALIDATION_FAILED` | Formato de dado do cliente, do valor ou do prazo, ou campo obrigatório ausente | Corrija pelos `details` |
| 422 | `LOAN_REQUEST_INVALID` | Valor ou prazo fora da faixa do hub | Ajuste pela faixa de `GET /ping` |
| 422 | `HUB_NOT_FOUND` | `hub_code` inexistente ou de outro parceiro | Corrija o `hub_code` |
| 422 | `WEBHOOK_NOT_CONFIGURED` | `POST /webhooks/test` sem URL de webhook cadastrada | Fale com o time de integrações |
| 429 | `RATE_LIMITED` | Limite de requisições por minuto | Aguarde o `Retry-After` |
| 429 | `CPF_DAILY_LIMIT_REACHED` | Limite diário de encerramentos sem contrato do CPF | Aguarde o `retry_after` |
| 500 | `INTERNAL_ERROR` | Erro da Wincred | Repita com espera |
| 503 | `SERVICE_UNAVAILABLE` | API desligada, serviço indisponível ou tempo máximo de 10 s excedido | Repita com espera |

## Os `reason` de `details`

`details` aparece em `422 VALIDATION_FAILED` e em `400 INVALID_REQUEST` sempre que o problema pode ser atribuído a um campo (tipo errado, campo desconhecido, campo duplicado).

| `reason` | Significado |
| - | - |
| `REQUIRED` | Campo obrigatório ausente ou vazio |
| `INVALID_FORMAT` | Formato ou tipo inválido |
| `INVALID_CHECK_DIGIT` | CPF com dígito verificador inválido ou com todos os dígitos iguais |
| `OUT_OF_RANGE` | Fora do tamanho ou da faixa permitida |
| `NOT_ALLOWED` | Valor bem formado, mas não aceito (por exemplo, código de país diferente de `55`) |
| `UNKNOWN_FIELD` | Campo que a API não reconhece |

Exemplo de `400` com campo desconhecido:

```json theme={null}
{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Requisição inválida.",
    "request_id": "req-rest",
    "details": [{ "field": "customer.mother_name", "reason": "UNKNOWN_FIELD" }]
  }
}
```

## Quando repetir

* **Repita com espera crescente** (por exemplo 1 s, 2 s, 4 s, com um teto) em `500`, `503`, timeout e erro de rede. `POST /referrals` é seguro de repetir: o mesmo CPF devolve o mesmo processo.
* **Respeite o `Retry-After`** (em segundos) nos dois `429`. Em `CPF_DAILY_LIMIT_REACHED`, o corpo traz também `retry_after`, em RFC 3339.
* **Corrija antes de repetir** em `400`, `401`, `403`, `404`, `413` e `422`: a mesma requisição produz o mesmo resultado.

Em qualquer erro, guarde o `request_id` e informe-o ao time de integrações: ele nos permite localizar a requisição rapidamente.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.