Códigos de erro

As falhas operacionais entregues por webhook (loan.invalid, installment.settlement_invalid, prepayment.invalid, repurchase.invalid, renegotiation.invalid) trazem o motivo em data.errors[], com um item cujo code é deste catálogo. A reprovação por critério do fundo (E0xx) tem forma própria, descrita na seção 6. Programe contra o code; description é texto para gente ler e pode mudar sem aviso.

"errors": [
  {
    "code": "loan_not_found",
    "title": "Operação não encontrada",
    "description": "loan_not_found for originator=OP-001 banker=None"
  }
]

Quatro regras de leitura:

• code é estável; description não é contrato. A description carrega o detalhe da ocorrência (qual código de parcela não bateu, qual valor divergiu). Nos códigos sem detalhe ela é o próprio literal do código ("description": "invalid_installment_state"), com uma exceção: unexpected_error_prepaying_installment chega com unexpected_error_prepaying_installment_v2. Use-a para diagnóstico, nunca para decidir fluxo.
• O item tem três campos: code, title e description. A coluna "Retentar?" das tabelas abaixo é desta documentação, não do payload: nenhum item de errors[] traz retryable.
• Só os unexpected_error_* valem uma nova tentativa da mesma chamada. São falhas da IORQ, não do pedido. A exceção é unexpected_error_processing_operation na recepção de arquivo (ver a seção 1), que carrega um erro do pedido. Nos demais códigos, a chamada falha de novo até você corrigir o que o código aponta.
• Um código pode aparecer em mais de um fluxo. loan_not_found sai na antecipação e na recompra; invalid_loan_state, na recompra e na renegociação. O type do evento diz de qual chamada veio.

1. Cessão (loan.invalid)

unexpected_error_processing_operation também sai, em loan.invalid, para erros do seu pedido na recepção de arquivo de lastro (POST /loan/files) e na atualização de dados da operação (PATCH /loan/operation-data): operação não encontrada, tipo de documento não permitido, payload inválido. Nesse caminho a description traz o texto da exceção, retentar a mesma chamada não resolve, e a operação não vai a invalid: o evento avisa que o arquivo ou o dado não foi aceito, e a operação segue no estado em que estava.

A reprovação na elegibilidade do fundo não usa este catálogo: ela chega com os códigos E0xx definidos na homologação do fundo. Ver a seção 6.

2. Liquidação (installment.settlement_invalid)

Divergência de valor na liquidação sai como settlement_conciliation_error; value_mismatch é da recompra.

3. Antecipação (prepayment.invalid)

4. Recompra (repurchase.invalid)

5. Renegociação (renegotiation.invalid)

credit_vehicle_not_found está reservado no catálogo e hoje não é emitido em nenhuma entrega.

6. Elegibilidade e covenant (E0xx)

Os códigos E0xx não pertencem ao catálogo operacional: são os critérios de elegibilidade e os covenants definidos por fundo na homologação, e o significado de cada um é o do regulamento daquele fundo. A numeração é compartilhada entre os serviços da IORQ e cresce com eles (já existe o E027); não a trate como uma faixa fechada. A lista dos critérios do seu fundo é a da homologação; ver Critérios de elegibilidade.

Três têm significado fixo em todos os fundos:

Os E0xx chegam de duas formas, conforme o ponto do fluxo em que a IORQ os emite:

Na forma serializada, reason_text é uma string JSON com um objeto {"E0xx": {"title", "description"}}, e errors chega nulo. Trate um reason_text que começa com { como JSON e leia os códigos de lá. Uma reprovação na elegibilidade da cessão chega assim:

"errors": null,
"reason_text": "{\"E006\": {\"title\": \"Prazo Acima do Limite\", \"description\": \"Prazo superior ao limite (36 meses)\"}}"

Na forma estruturada, cada critério é um item de errors[], com title e description vindos da regra:

"errors": [
  {
    "code": "E026",
    "title": "Renegociação Reprovada em Covenant",
    "description": "Renegociação reprovada na avaliação de covenants: ..."
  }
]

A forma serializada é um resquício do contrato v1, preservado para não mudar o corpo que os integradores v1 já recebem.

7. Como o mesmo motivo aparece no v1

No corpo legado o motivo vai em data.reason, e o tipo dele depende de onde o motivo estava no v2:

• Código deste catálogo em errors[]: reason é a string que a description do item carrega, e não o objeto: "reason": "loan_not_found for originator=OP-001 banker=None".
• E0xx em errors[] (lote de renegociação, E026): reason é o objeto {"E026": {"title": ..., "description": ...}}.
• reason_text (a forma serializada dos E0xx, inclusive E023 e E024, e as confirmações de sucesso): reason é a mesma string. Um E0xx que chega assim no v1 é um JSON dentro de uma string, não um objeto.

Os textos v1 são estáveis por compatibilidade, não por contrato. Um integrador v1 que quiser o código sem parsear texto migra para o v2. O caminho inverso vale para o envelope v2 remontado a partir do v1, o caso de produção hoje: a IORQ só devolve um motivo em texto a errors[] quando reconhece o texto de um código deste catálogo, e o resto chega em reason_text (ver Catálogo de eventos). Ver também Contrato v1 (legado).

8. Próximos passos