Erros e códigos de status
Esta página é a referência consolidada dos envelopes de resposta usados por todas as rotas da API do domínio de empréstimos. A documentação de cada rota lista os códigos de status que ela emite; esta página documenta o formato de cada envelope e o catálogo de valores de code nomeados que você pode receber.
Leia-a uma vez antes de integrar; volte a ela sempre que um status diferente de 2xx surpreender você.
Catálogo de códigos de status
| Status | Quando aparece | Rota de exemplo |
|---|---|---|
200 OK | Leitura bem-sucedida, repetição idempotente, cancelamento lógico, lote processado, transição de status. | Todas as rotas que não são de criação. |
201 Created | Criação bem-sucedida pela primeira vez em uma rota de registro único. | POST /borrowers. |
202 Accepted | Importação assíncrona iniciada — o trabalho continua em segundo plano. | POST /imports. |
204 No Content | Não é retornado atualmente por nenhuma rota do domínio de empréstimos. | — |
400 Bad Request | Falha de validação da requisição: JSON malformado, query malformada, violação de schema. | Todas as rotas de escrita. |
401 Unauthorized | Sem cabeçalho Authorization, token desconhecido ou token revogado. | Todas as rotas. |
403 Forbidden | O chamador é uma conta de investidor; investidores não podem usar a API de dados de monitoramento (MONITORING_INVESTOR_FORBIDDEN). Um ?unmask=true por quem não é administrador não retorna 403: retorna 200 com a PII mascarada. | Todas as rotas. |
404 Not Found | O recurso não existe ou pertence a outra organização. | Todas as rotas que referenciam um recurso. |
409 Conflict | Já existe uma linha ativa com este id, ou uma Idempotency-Key foi reutilizada para uma transição de status diferente, ou a fase de commit não encontrou o arquivo enviado. | POST /borrowers, PATCH /loans/.../status, POST /imports/{id}/commit. |
413 Payload Too Large | Um lote de NDJSON excede o limite de linhas ou de bytes. | POST /bulk/{entity}. |
422 Unprocessable Entity | Uma linha referenciada não existe como ativa no mesmo portfólio (REFERENCED_ENTITY_NOT_FOUND), ou a transição de status solicitada não está na matriz de transição (INVALID_STATUS_TRANSITION). Falhas de validação usam 400. | POST /loans, POST /payments, PATCH /loans/{loanRef}/status. |
429 Too Many Requests | Limite de taxa excedido. A plataforma aplica limites de taxa por organização; o cabeçalho de resposta Retry-After indica os segundos. | Todas as rotas. |
500 Internal Server Error | Erro não tratado da plataforma. Trate como transitório; é seguro tentar novamente com o mesmo Idempotency-Key. | Todas as rotas. |
Trate qualquer 4xx diferente de 429 como um defeito da requisição — a lógica do seu cliente deve rejeitar a entrada em vez de tentar novamente. Trate 429 e 500 como transitórios e tente novamente com backoff; um Idempotency-Key torna a nova tentativa segura.
Envelopes padrão
A API do domínio de empréstimos usa três envelopes de resposta para códigos de status que não indicam sucesso. O formato do envelope indica que tipo de falha você está vendo.
Envelope de validação — 400 Bad Request
Usado para violações de schema, parâmetros de query malformados e caminhos malformados.
{
"error": "Validation failed",
"fieldErrors": [
{ "path": "interestRateApr", "message": "interestRateApr must be >= 0" },
{ "path": "termMonths", "message": "termMonths must be > 0" }
]
}| Campo | Tipo | Observações |
|---|---|---|
error | string | Resumo curto e legível. |
fieldErrors[].path | string | Caminho com pontos até o campo com problema. (root) indica o próprio corpo, por exemplo quando a interpretação do JSON falhou. |
fieldErrors[].message | string | Explicação legível. |
Algumas rotas emitem errors[] em vez de fieldErrors[] para falhas em parâmetros de query (a convenção do framework varia conforme a interface). O formato path/message é idêntico; trate os dois nomes de array como intercambiáveis ao fazer o parsing.
Envelope com código nomeado — 4xx
Usado quando a falha tem uma causa específica que a plataforma nomeia com um valor de code estável. A presença de fieldErrors é opcional e depende de a falha poder ser atribuída a um campo específico.
{
"error": "a borrower with this id already exists",
"code": "ID_CONFLICT",
"fieldErrors": [
{ "path": "id", "message": "a borrower with this id already exists" }
]
}| Campo | Tipo | Observações |
|---|---|---|
error | string | Resumo legível. |
code | string | Código estável, legível por máquina; veja o glossário. |
fieldErrors[] | array | ausente | Presente quando a falha aponta para um campo específico. |
Alguns envelopes trazem contexto estruturado adicional — por exemplo, batch_too_large inclui um bloco fieldErrors indicando o limite excedido. A documentação de cada rota indica esses casos.
Envelope de erro simples — 404 / 401
Usado em respostas sucintas, nas quais contexto adicional não ajudaria o chamador. 404 é o exemplo típico:
{ "error": "Not found" }Algumas rotas retornam { "error": "...", "code": "NOT_FOUND" }; trate a presença ou ausência de code em um 404 como informativa, não como algo de que a lógica dependa.
Dois espaços de códigos: maiúsculas vs. minúsculas
A API do domínio de empréstimos usa dois namespaces distintos de code, separados intencionalmente pela forma de ingestão:
- Rotas de registro único (POSTs, PATCHes, o cancelamento e os GETs de conciliação) emitem valores de
codeemUPPER_CASE:ID_CONFLICT,PORTFOLIO_NOT_FOUND,REFERENCED_ENTITY_NOT_FOUND,INVALID_STATUS_TRANSITION,CHECK_VIOLATION,NOT_FOUND,UNKNOWN_KIND,COMMIT_FAILED,IDEMPOTENCY_CONFLICT,IDEMPOTENCY_KEY_REUSED,MONITORING_INVESTOR_FORBIDDEN. As rotas de NDJSON em lote também retornamMONITORING_INVESTOR_FORBIDDENem maiúsculas. - Rotas de NDJSON em lote emitem valores de
codeemlower_case:batch_too_large,portfolio_not_found,portfolio_id_required,invalid_body,invalid_json, além dos códigos por linha documentados abaixo.
Ao ramificar a lógica do seu cliente com base em code, respeite exatamente maiúsculas e minúsculas. Os dois espaços de códigos são estáveis cada um por si; não os normalize.
Glossário de códigos de erro
A plataforma associa um code estável a cada modo de falha nomeado. Use-os para ramificações programáticas; o texto da mensagem em error pode mudar.
Espaço de códigos de registro único
| Código | Status | Emitido por | Gatilho |
|---|---|---|---|
ID_CONFLICT | 409 | POST /borrowers, POST /loans, POST /payments. | Já existe uma linha ativa com o mesmo id. |
PORTFOLIO_NOT_FOUND | 404 | Todas as rotas de escrita de registro único. | O portfolioId do corpo não existe na sua organização. |
REFERENCED_ENTITY_NOT_FOUND | 422 | POST /loans, POST /payments. | borrowerId ou loanId referencia uma linha que não existe como ativa no mesmo portfólio. |
INVALID_STATUS_TRANSITION | 422 | PATCH /loans/{loanRef}/status. | O par de status origem/destino não está na matriz de transição. |
IDEMPOTENCY_CONFLICT | 409 | PATCH /loans/{loanRef}/status. | A Idempotency-Key já foi usada para uma transição de status diferente. Envie a nova transição com uma nova chave. |
IDEMPOTENCY_KEY_REUSED | 409 | POST /imports. | A Idempotency-Key já foi usada para uma importação com parâmetros de requisição diferentes (kind, filename, sizeBytes, …). A resposta inclui importId e mismatchedFields. Envie a nova importação com uma nova chave. |
MONITORING_INVESTOR_FORBIDDEN | 403 | Todas as rotas de empréstimos de monitoramento, incluindo NDJSON em lote. | O chamador é uma conta de investidor; investidores não podem usar a API de dados de monitoramento. |
CHECK_VIOLATION | 400 | POST /payments. | Uma regra de dados falhou (normalmente a invariante de perdão; a camada de schema rejeita o mesmo formato já na validação). |
NOT_FOUND | 404 | GET /borrowers/{id}, GET /payments/{id}, PATCH /loans/.../status, POST /payments/{id}/cancel, GET /loans/{externalId}. | A linha consultada não existe como ativa no escopo informado, ou pertence a outra organização. |
UNKNOWN_KIND | 400 | POST /imports. | kind não é um dos seis tipos de empréstimo. A resposta inclui um array allowed. |
COMMIT_FAILED | 409 | POST /imports/{id}/commit. | A plataforma não encontrou o arquivo enviado; normalmente o upload nunca terminou. Refaça o upload e, em seguida, o commit. |
Espaço de códigos de NDJSON em lote
| Código | Status | Gatilho |
|---|---|---|
batch_too_large | 413 | O corpo excede 10 000 linhas ou 10 MB. error e fieldErrors[].message distinguem o limite de linhas do limite de bytes. |
portfolio_id_required | 400 | ?portfolioId=<UUID> está ausente ou não é um UUID válido. |
portfolio_not_found | 404 | O ?portfolioId= não existe como portfólio ativo na sua organização. |
invalid_body | 400 | O corpo da requisição não pôde ser lido como texto. |
invalid_json | (por linha) | Uma linha não é JSON válido. Aparece dentro do array errors[] por linha; o lote retorna 200. |
Um código que não esteja neste glossário indica que a plataforma adicionou um novo código nomeado desde a última revisão desta página. Sempre registre o valor de code literalmente junto com o erro da sua aplicação, para que a equipe de engenharia possa fazer a correlação.
Códigos de erro por linha (lote e importações assíncronas)
O NDJSON em lote e as importações assíncronas retornam erros por linha. A interface em lote usa um conjunto de valores; a interface de importações assíncronas usa um conjunto parecido, mas um pouco diferente (em especial, inclui validation_error em vez de validation_failed, por ser uma interface mais antiga). As entradas por linha descrevem falhas de linhas individuais dentro de um lote bem-sucedido, não falhas de envelope.
Códigos por linha do NDJSON em lote
| Código por linha | Gatilho |
|---|---|
validation_failed | A linha falhou na validação de schema. O campo message traz os erros de validação. |
fk_violation | Uma referência de chave estrangeira na linha (por exemplo, borrowerId, loanId) não corresponde a uma linha ativa no mesmo portfólio. |
unique_violation | Já existe uma linha ativa com o mesmo (portfolio, externalId) ou id. (Não há um código por linha id_conflict separado; os dois tipos de colisão de ID do chamador aparecem aqui.) |
check_violation | Uma regra de dados falhou — normalmente a regra de perdão em um pagamento. |
db_error | Um erro inesperado ao armazenar esta linha. A linha é informada como falha; o lote continua. |
invalid_json | A linha não era JSON válido. A plataforma processa o restante do lote. |
Códigos por linha das importações assíncronas
| Código por linha | Gatilho |
|---|---|
parse_error | A linha não era JSON válido. |
validation_error | A linha falhou na validação de schema. |
portfolio_mismatch | O portfolioId da linha não corresponde ao portfólio âncora da importação. |
processor_error | Uma falha inesperada do handler durante o processamento desta linha. |
Erros ao armazenar uma linha (uma referência ausente, uma duplicata, uma regra de dados violada) aparecem sob um dos códigos acima, com o detalhe em errorMessage.
Erros por linha nunca sobem para uma resposta de nível superior diferente de 200 na interface em lote — o lote como um todo teve sucesso se a requisição em si estava bem formada; os códigos por linha informam o que foi gravado.
Semântica de novas tentativas
Um padrão seguro de novas tentativas para qualquer rota de escrita é:
- Gere um
Idempotency-Keydeterminístico por operação lógica. Um UUIDv4 mais um discriminador de rota funciona. - Envie a requisição com a chave.
- Em qualquer um de
2xx,409 ID_CONFLICT,409 IDEMPOTENCY_CONFLICT,409 IDEMPOTENCY_KEY_REUSED,404,403,400,413ou422— não tente novamente. O resultado é definitivo. - Em
429— tente novamente após o tempo indicado no cabeçalhoRetry-After. - Em
500ou em um erro de rede — tente novamente até um número pequeno e fixo de vezes, com backoff exponencial. OIdempotency-Keytorna a nova tentativa segura, tenha a primeira tentativa chegado ou não.
Uma nova tentativa de uma requisição bem-sucedida com o mesmo Idempotency-Key retorna a mesma resposta da original, com reused: true na entidade afetada. Esta é a recuperação canônica de uma falha de rede no caminho feliz.
O que a plataforma nunca retorna
Para a depuração operacional, é útil conhecer também o que não acontece:
- Nenhum código de status
5xxé tratado como funcionalidade pela plataforma. Um500é sempre um bug a ser corrigido; nunca escreva lógica no cliente que dependa de um formato específico de500. - Nenhuma resposta
404revela informações de tenant. Um404para uma linha que existe em outra organização é idêntico a um404para uma linha que não existe em lugar nenhum. Não escreva lógica no cliente que deduza a existência entre tenants. - Nenhuma resposta de sucesso traz um campo de corpo chamado
success: false. O código de status é a fonte de verdade sobre o sucesso da chamada; o formato do corpo traz os detalhes. - Nenhuma rota de escrita retorna o próprio UUID no estilo de parâmetro de caminho (cabeçalho "Location"). O UUID criado aparece no campo
iddo corpo da resposta.