Tratamento de erros

Todas as respostas de erro seguem o mesmo envelope, com um code estável que você pode tratar programaticamente — mensagens podem mudar, códigos não.

{
  "error": {
    "code": "ERRO_VALIDACAO",
    "message": "CPF inválido",
    "details": {
      "campo": "cpf",
      "restricoes": { "matches": "cpf deve conter exatamente 11 dígitos." }
    }
  }
}

O campo details é opcional e varia por tipo de erro (ex.: campos de validação, ou dados do upstream com segredos já redigidos).

Catálogo de códigos

Como tratar

• Trate pelo code, não pela message. As mensagens são para humanos e podem mudar.
• 429 e 5xx (incl. DATAPREV_INDISPONIVEL) são transitórios: faça retry com backoff, respeitando o Retry-After quando presente.
• 4xx de validação/negócio (ERRO_VALIDACAO, MARGEM_INSUFICIENTE…) não adianta repetir sem corrigir a entrada.
• PARCEIRO_NAO_HABILITADO e OPERACAO_NAO_PROVISIONADA são as exceções entre os 5xx: não são transitórios e não se resolvem corrigindo o payload — é configuração do nosso lado. A diferença: o primeiro é sobre o parceiro como um todo (abra um chamado); o segundo é sobre um cadastro específico desta operação, então depois da confirmação do suporte a mesma requisição funciona — repita com a mesma Idempotency-Key, informando o número do empréstimo no chamado.
• UPSTREAM_INALCANCAVEL é o oposto: a requisição não chegou ao destino, nada foi aplicado, e repetir com a mesma Idempotency-Key é seguro de imediato.