Erros & Status

Todo erro segue o mesmo envelope, com um codigo estável. Ramifique a sua lógica pelo codigo — não pela mensagem (que pode mudar).

Formato do erro

{
  "erro": "Consentimento do titular e obrigatorio",  // mensagem legível (pode mudar)
  "codigo": "consentimento_ausente",                // slug ESTÁVEL — use este
  "campos": [                                       // opcional (erros de validação)
    { "campo": "consentimento", "motivo": "deve ser true" }
  ],
  "request_id": "4a0ee7e3-5ae0-43e4-8045-2d64f5951a4b"  // informe ao suporte
}

Retry-After. Nos status 429, 502 e 503, a resposta traz o header Retry-After (em segundos) indicando quando tentar de novo.

Códigos HTTP

Status	Significado	O que fazer
2xx	Sucesso	Siga o fluxo
400	Dados da requisição inválidos	Corrija o corpo/parâmetros
401	API Key ausente ou inválida	Cheque o header `X-API-Key`
403	Fora do escopo da chave	Peça o escopo ao gestor
404	Recurso não encontrado (ou não é seu)	Confira o id
409	Conflito (requisição idêntica em andamento)	Aguarde e não reenvie
422	Regra de negócio não satisfeita	Veja `codigo`/`campos`
429	Rate limit estourado	Espere o `Retry-After`
502/503	Origem (banco/CRM) indisponível	Retry com backoff
500	Erro interno da FortunCred	Reporte com o `request_id`

Códigos de erro (`codigo`)

Autenticação & permissão

`codigo`	Status	Significado
`auth_invalid`	401	API Key ausente, inválida ou inativa.
`auth_inactive`	403	Parceiro desativado.
`sem_permissao`	403	A chave não tem escopo para este recurso.

Validação de entrada

`codigo`	Status	Significado
`campo_obrigatorio`	400	Falta um campo obrigatório (lista em `campos`).
`campo_invalido`	400	Valor malformado — ex.: CPF com dígito inválido, CEP fora de 8 dígitos, `sexo` ≠ M/F.

Regras de negócio

`codigo`	Status	Significado
`divergencia_titular`	422	`cpf`/`nome`/`data_nascimento` da análise divergem do lead cadastrado.
`consentimento_ausente`	422	Falta o consentimento LGPD do titular (ou seus metadados).
`banco_invalido`	422	Banco fora do catálogo. Veja os válidos em `campos.validos`.

Idempotência & conflito

`codigo`	Status	Significado
`idempotency_conflito`	422	Mesma `Idempotency-Key` usada com um corpo diferente.
`idempotency_em_andamento`	409	Uma requisição com essa chave ainda está processando. Aguarde.
`conflito`	409	Conflito genérico de estado.

Limites & disponibilidade

`codigo`	Status	Significado
`rate_limited`	429	Limite de requisições estourado. Respeite o `Retry-After`.
`banco_indisponivel`	502	A integração do banco falhou (transitório). Retry.
`origem_indisponivel`	502/503	O sistema de origem (CRM) está indisponível. Retry com backoff.
`recurso_indisponivel`	403	Recurso temporariamente desabilitado nesta API.

Não encontrado & interno

`codigo`	Status	Significado
`nao_encontrado`	404	Recurso inexistente ou que não pertence à sua unidade.
`lead_nao_encontrado`	404	Lead não existe (ou não é seu).
`analise_nao_encontrada`	404	Análise não existe (ou não é sua).
`rota_nao_encontrada`	404	Endpoint inexistente. Confira o caminho.
`erro_interno`	500	Erro inesperado da FortunCred. Reporte com o `request_id`.