Erros

A API usa os códigos de status HTTP para indicar se uma requisição foi aceita. Resultados de negócio, como um cliente não qualificado ou uma proposta recusada pelo banco, são respostas de sucesso e vêm no corpo da resposta.

Códigos de status

Status	Significado
200	Requisição processada.
201	Recurso criado, como um arquivo enviado.
202	Solicitação aceita para processamento assíncrono.
400	Requisição inválida: campo ausente, formato incorreto ou combinação de parâmetros não permitida.
401	Chave de API ausente ou não aceita. Veja Autenticação.
402	Saldo de créditos insuficiente.
403	A chave não tem acesso a este recurso.
404	Recurso não encontrado para o parceiro.
409	Conflito com uma solicitação existente.
413	Arquivo ou corpo maior que o limite permitido.
422	A solicitação é válida, mas não atende aos requisitos para envio ao banco.
5xx	Falha temporária. Repita a requisição com espera crescente entre as tentativas.

Formato do erro

A maioria dos erros segue o formato abaixo. message é um texto ou, em erros de validação, uma lista de textos.

{
  "statusCode": 400,
  "message": ["clientInfo.federalId não deve estar vazio"],
  "error": "Bad Request"
}

Erros com tratamento específico trazem um code estável. Use code na lógica da integração e message apenas para exibir ou registrar.

{
  "code": "IDEMPOTENCY_PAYLOAD_MISMATCH",
  "message": "A chave de idempotência já foi usada com outro conteúdo de solicitação."
}

Códigos de erro

Status	code	Situação
400	REQUEST_SELECTOR_INVALID	Em Buscar solicitação, foram informados requestId e idempotencyKey, ou nenhum dos dois.
404	REQUEST_NOT_FOUND	Nenhuma solicitação de proposta encontrada para o parceiro.
409	IDEMPOTENCY_PAYLOAD_MISMATCH	A idempotencyKey já foi usada com outro conteúdo. Veja Idempotência.
409	ACTIVE_REQUEST	Já existe uma solicitação ativa para o mesmo cliente e operação.
422	ADMISSION_INVALID	A proposta não atende aos requisitos de inclusão. Os campos com problema vêm em wrongFields.
422	OPPORTUNITY_UNAVAILABLE	A condição escolhida não está mais disponível. Faça uma nova qualificação ou simulação.

Erros de validação (400)

Cada item de message descreve um campo, com o caminho completo do campo no corpo da requisição, como clientInfo.federalId. Corrija os campos indicados antes de repetir a requisição; repetir sem alterações produz o mesmo erro.

Saldo insuficiente (402)

Quando a cobrança está ativa e o saldo de créditos do parceiro não cobre a operação, a API responde com HTTP 402:

{
  "success": false,
  "message": "Saldo de créditos insuficiente para executar esta operação",
  "endpointCode": "qualification",
  "creditCost": 1
}

endpointCode identifica a operação tarifada e creditCost, o custo em créditos. Peça à sua rede parceira para recarregar a carteira antes de repetir.

Resultados de negócio

Qualificação

A qualificação responde com HTTP 200 mesmo quando o cliente não pode ser qualificado. O resultado vem em qualification.status:

qualification.status	Significado
qualificado	Cliente qualificado no convênio. Veja as oportunidades em creditDetail.
nao-qualificado	Cliente não qualificado no convênio.
faltando-info	Faltam dados do cliente para qualificar. Veja qualification.message.
info-invalida	Algum dado informado é inválido. Veja qualification.message.
desconhecido	Não foram encontradas informações básicas sobre o cliente.
indisponivel	A consulta não está disponível no momento. Tente novamente mais tarde.
faltando-configuracao	Falta uma configuração da rede parceira para este convênio.
captcha-requerido	A consulta exige uma verificação adicional e responde com HTTP 202. Essa etapa não está disponível na API pública; fale com o suporte.
qualificacao-falhou	Falha ao processar a qualificação. Tente novamente mais tarde.

Trate qualquer outro valor como indisponivel.

Propostas

O resultado do envio de uma proposta vem em outcome.status:

outcome.status	Significado
created	Proposta criada no banco.
processing	Envio em andamento. Acompanhe a solicitação.
action-required	O cliente ou o parceiro precisa agir. Veja nextAction.
manual-review	A proposta segue para tratamento manual.
rejected	A proposta foi recusada. Veja outcome.code e outcome.message.
failed	O envio falhou. Veja outcome.message e outcome.wrongFields.

Repetir com segurança

• Repita requisições que falharam com 5xx, por tempo esgotado ou por erro de rede, com espera crescente entre as tentativas.
• Não repita requisições que falharam com 4xx sem corrigir a causa.
• Para enviar propostas, use Criar proposta assíncrona com idempotencyKey. Assim, uma nova tentativa nunca cria uma proposta duplicada.