Erros - Wincred docs

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

{
  "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:

{
  "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.