Códigos de erro

1. Formato

{
  "error_code": "field_missing",
  "message": "Field 'fund_id' is required",
  "field": "fund_id",
  "request_id": "req_8a3f2c1b9d4e"
}

Em rejeições de elegibilidade via webhook, a forma é:

{
  "event": "loan_rejected",
  "data": {
    "reason": "<código definido na homologação do fundo>",
    "reason_detail": "Explicação humana com os valores que causaram a rejeição"
  }
}

Programe contra error_code e reason — não contra o texto da mensagem (que pode mudar).

2. Códigos HTTP

HTTP	Significado	Estratégia
`200`	Sucesso (operação síncrona)	Processar resposta
`201`	Criado (operação aceita para processamento assíncrono)	Aguardar webhook
`400`	Payload inválido — JSON malformado, campo ausente, formato errado	Corrigir e reenviar (não retentar idêntico)
`401`	Não autenticado — token ausente, expirado ou inválido	Renovar via `POST /token`
`403`	Sem permissão — token válido mas sem escopo	Revisar escopo contratado
`404`	Recurso inexistente — `originator_proposal_code` não encontrado	Verificar se a operação existe
`409`	Conflito — chave de idempotência já existe com payload diferente	Usar nova chave ou ajustar payload
`422`	Estado inválido — operação não pode receber esta ação	Consultar estado atual via `GET`
`429`	Rate limit excedido	Backoff exponencial — ver Rate limits
`500`	Erro inesperado IORQ	Retentar com backoff; abrir chamado se persistir
`503`	Serviço temporariamente indisponível	Retentar com backoff

3. Códigos canônicos de erro (síncronos)

Validação de payload

`error_code`	HTTP	Significado
`invalid_json`	400	JSON do `loan_data` malformado
`field_missing`	400	Campo obrigatório ausente
`field_invalid_format`	400	Tipo errado ou formato inválido (ex: data fora do ISO 8601)
`field_out_of_range`	400	Valor fora dos limites aceitos

Upload de arquivos

`error_code`	HTTP	Significado
`file_type_invalid`	400	Arquivo não é PDF
`file_too_large`	400	Arquivo maior que 2 MB
`file_name_mismatch`	400	Nome do PDF não bate com `backing_documents[].value`
`file_count_exceeded`	400	Mais de 5 arquivos na requisição
`file_corrupted`	400	PDF inválido ou criptografado

Autenticação e autorização

`error_code`	HTTP	Significado
`not_authenticated`	401	Header `Authorization` ausente ou malformado
`token_expired`	401	Token expirado
`token_invalid`	401	Assinatura inválida
`scope_insufficient`	403	Token sem escopo para o endpoint
`fund_not_allowed`	403	`fund_id` fora da lista permitida

Estado e idempotência

`error_code`	HTTP	Significado
`resource_not_found`	404	`originator_proposal_code` não encontrado
`idempotency_conflict`	409	Chave já existe com payload diferente
`invalid_state_transition`	422	Operação não pode receber essa ação no estado atual

Sistema

`error_code`	HTTP	Significado
`rate_limited`	429	Quota excedida — ver Rate limits
`internal_error`	500	Erro inesperado
`service_unavailable`	503	Manutenção ou degradação

4. Motivos de rejeição (webhook `loan_rejected`)

Os motivos canônicos de rejeição são definidos por fundo no momento em que os critérios de elegibilidade são desenhados. Cada reason corresponde a uma regra implementada para o regulamento do FIDC e a política do originador.

Ao homologar um fundo, o time da IORQ entrega a lista de reason aplicáveis e seus significados. Ver o processo de definição em Critérios de elegibilidade.

O campo reason sempre vem no formato snake_case e é estável dentro do ciclo de vida do fundo — mudanças requerem comunicação prévia.

5. Como reportar um erro

Para erros 5xx ou comportamento inesperado:

Capture o header x-request-id da resposta
Anote o originator_proposal_code envolvido (se aplicável)
Anote o horário da chamada com timezone
Abra um ticket no canal de suporte combinado com a IORQ

6. Próximos passos

Continuar — Rate limits

Quotas, headers e estratégia de retentativa.

Aprofundar — Critérios de elegibilidade

Cada motivo de rejeição em detalhe.