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

HTTP	`code`	Quando acontece
400	`ERRO_VALIDACAO`	Payload inválido (campo faltando, formato errado)
400	`IDEMPOTENCY_KEY_OBRIGATORIA`	Faltou o header `Idempotency-Key`
401	`CREDENCIAL_INVALIDA`	Token ausente, inválido ou expirado
401	`AUTORIZACAO_PENDENTE`	O trabalhador ainda não autorizou
401	`AUTORIZACAO_EXPIRADA`	A autorização do trabalhador venceu
403	`ESCOPO_INSUFICIENTE`	A credencial não tem o escopo necessário
404	`EMPRESTIMO_NAO_ENCONTRADO`	Empréstimo inexistente ou de outro parceiro
404	`SEM_EMPREGADOR_AUTORIZADO`	Nenhum vínculo autorizado para o CPF
409	`CONFLITO_IDEMPOTENCIA`	Conflito de chave de idempotência
422	`CONSULTA_MARGEM_NAO_ENCONTRADA`	Falta uma consulta de margem válida
422	`MARGEM_INSUFICIENTE`	A parcela excede a margem disponível
422	`ERRO_NEGOCIO`	Regra de negócio do BaaS impediu a operação
429	`RATE_LIMIT_EXCEDIDO`	Limite por credencial excedido (veja `Retry-After`)
502 / 503 / 504	`DATAPREV_INDISPONIVEL`	O Dataprev está indisponível — tente de novo
500	`ERRO_INTERNO`	Erro interno (sem detalhes em produção)

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.

Em chamadas idempotentes, é seguro repetir após um 5xx ou timeout usando a mesma Idempotency-Key — você recebe a resposta original se a operação já tiver sido processada.