Waafir
Esta página é uma tradução automática pendente de revisão humana. Pode conter erros.

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

StatusQuando apareceRota de exemplo
200 OKLeitura 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 CreatedCriação bem-sucedida pela primeira vez em uma rota de registro único.POST /borrowers.
202 AcceptedImportação assíncrona iniciada — o trabalho continua em segundo plano.POST /imports.
204 No ContentNão é retornado atualmente por nenhuma rota do domínio de empréstimos.—
400 Bad RequestFalha de validação da requisição: JSON malformado, query malformada, violação de schema.Todas as rotas de escrita.
401 UnauthorizedSem cabeçalho Authorization, token desconhecido ou token revogado.Todas as rotas.
403 ForbiddenO 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 FoundO recurso não existe ou pertence a outra organização.Todas as rotas que referenciam um recurso.
409 ConflictJá 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 LargeUm lote de NDJSON excede o limite de linhas ou de bytes.POST /bulk/{entity}.
422 Unprocessable EntityUma 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 RequestsLimite 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 ErrorErro 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" }
  ]
}
CampoTipoObservações
errorstringResumo curto e legível.
fieldErrors[].pathstringCaminho com pontos até o campo com problema. (root) indica o próprio corpo, por exemplo quando a interpretação do JSON falhou.
fieldErrors[].messagestringExplicaçã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" }
  ]
}
CampoTipoObservações
errorstringResumo legível.
codestringCódigo estável, legível por máquina; veja o glossário.
fieldErrors[]array | ausentePresente 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 code em UPPER_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 retornam MONITORING_INVESTOR_FORBIDDEN em maiúsculas.
  • Rotas de NDJSON em lote emitem valores de code em lower_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ódigoStatusEmitido porGatilho
ID_CONFLICT409POST /borrowers, POST /loans, POST /payments.Já existe uma linha ativa com o mesmo id.
PORTFOLIO_NOT_FOUND404Todas as rotas de escrita de registro único.O portfolioId do corpo não existe na sua organização.
REFERENCED_ENTITY_NOT_FOUND422POST /loans, POST /payments.borrowerId ou loanId referencia uma linha que não existe como ativa no mesmo portfólio.
INVALID_STATUS_TRANSITION422PATCH /loans/{loanRef}/status.O par de status origem/destino não está na matriz de transição.
IDEMPOTENCY_CONFLICT409PATCH /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_REUSED409POST /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_FORBIDDEN403Todas 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_VIOLATION400POST /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_FOUND404GET /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_KIND400POST /imports.kind não é um dos seis tipos de empréstimo. A resposta inclui um array allowed.
COMMIT_FAILED409POST /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ódigoStatusGatilho
batch_too_large413O corpo excede 10 000 linhas ou 10 MB. error e fieldErrors[].message distinguem o limite de linhas do limite de bytes.
portfolio_id_required400?portfolioId=<UUID> está ausente ou não é um UUID válido.
portfolio_not_found404O ?portfolioId= não existe como portfólio ativo na sua organização.
invalid_body400O 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 linhaGatilho
validation_failedA linha falhou na validação de schema. O campo message traz os erros de validação.
fk_violationUma referência de chave estrangeira na linha (por exemplo, borrowerId, loanId) não corresponde a uma linha ativa no mesmo portfólio.
unique_violationJá 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_violationUma regra de dados falhou — normalmente a regra de perdão em um pagamento.
db_errorUm erro inesperado ao armazenar esta linha. A linha é informada como falha; o lote continua.
invalid_jsonA 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 linhaGatilho
parse_errorA linha não era JSON válido.
validation_errorA linha falhou na validação de schema.
portfolio_mismatchO portfolioId da linha não corresponde ao portfólio âncora da importação.
processor_errorUma 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 é:

  1. Gere um Idempotency-Key determinístico por operação lógica. Um UUIDv4 mais um discriminador de rota funciona.
  2. Envie a requisição com a chave.
  3. Em qualquer um de 2xx, 409 ID_CONFLICT, 409 IDEMPOTENCY_CONFLICT, 409 IDEMPOTENCY_KEY_REUSED, 404, 403, 400, 413 ou 422 — não tente novamente. O resultado é definitivo.
  4. Em 429 — tente novamente após o tempo indicado no cabeçalho Retry-After.
  5. Em 500 ou em um erro de rede — tente novamente até um número pequeno e fixo de vezes, com backoff exponencial. O Idempotency-Key torna 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. Um 500 é sempre um bug a ser corrigido; nunca escreva lógica no cliente que dependa de um formato específico de 500.
  • Nenhuma resposta 404 revela informações de tenant. Um 404 para uma linha que existe em outra organização é idêntico a um 404 para 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 id do corpo da resposta.