Lender error list

Error format Lender returns most errors as RFC 9457 problem details with the application/problem+json media type. A rate-limit refusal answers a flat {code, title, message} body on application/json.

{
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "validation failed",
  "errors": [
    {
      "location": "body.grossRequestedAmount",
      "message": "expected string",
      "value": 50000
    }
  ]
}

{
  "code": 429,
  "title": "rate_limit_exceeded",
  "message": "rate limit exceeded"
}

Field definitions

status – The HTTP status code.
title – The status name, such as Unprocessable Entity.
detail – What went wrong on this occurrence. Below 500, it describes the specific refusal. For 500, 502, and 503, it carries a fixed generic value instead of the underlying cause.
errors – Optional list of schema-validation details. Each entry carries a location, a message, and the value Lender received.
type – Present on errors the framework produces, where it carries the RFC 9457 default about:blank.

The flat rate-limit body carries code, title, and message instead. Its code repeats the numeric HTTP status. Its title names the refusal and its message explains it in one sentence. Neither string varies with the caller or names your remaining quota. Branch on the HTTP status and the content type, then read detail for the specific refusal. Authorization and idempotency middleware can answer in their own response formats.

Client errors

Lender answers a 4xx when the request is the problem, and detail names the specific refusal. Lender scopes a lookup to the caller’s tenant and to the parent named in the path. An identifier that resolves outside that scope answers the same way as an identifier that resolves to nothing. A command needs a subject on the caller identity, because Lender records that subject as the actor behind the change. Byte limits apply twice: the framework limits the request body, and each file-ingestion surface limits the file it accepts. Schema validation runs before the handler and fills errors with one entry per rejected location. A business rule runs inside the handler and answers with detail alone. Three examples: a currency assertion that disagrees with the loan, a set composition that mixes currencies, and a fund configured without a registry.

Status	What it means	What to do
`400`	The request arrives without a body, or the body is not the exact JSON shape the operation reads.	Send a body that matches the operation’s schema, then repeat the request.
`400`	The `X-Idempotency` header is longer than the operation accepts.	Send a shorter key, then repeat the request.
`401`	The request arrives without an authenticated identity.	Send a valid bearer token, then repeat the request.
`401`	The identity is authenticated, and its subject is empty.	Use a token whose subject identifies the caller.
`403`	The request lacks a validated tenant identity for the resource the operation works on.	Use a token scoped to the tenant that holds the resource, then repeat the request.
`404`	The identifier in the path names a resource this tenant does not hold.	Check the identifier, and check the tenant the token is scoped to.
`404`	The resource exists, and the parent named in the path does not hold it.	List the parent’s own resources, then use an identifier from that list.
`409`	Another request carrying the same `X-Idempotency` value is still running.	Wait the `Retry-After` interval, then read the resource. Do not send the command again.
`422`	The `X-Idempotency` value was already used for a request with a different body.	Do not send this command under a new key. Read the outcome of the original request first, then decide.
`409`	The `idempotencyKey` in the body names a term already recorded with different content.	Read the term on record. A new key records a second term for the same set.
`409`	The resource sits at a different lifecycle step, or it was already closed.	Read the resource, then act from the step it is at.
`409`	Another writer changed the resource during the request.	Read the resource again, then repeat the request.
`409`	An external registry already accepted this exact command.	Read the protocol on record instead of issuing the command again.
`413`	The request body is larger than the operation accepts.	Send a smaller body.
`413`	The uploaded file is larger than the ingestion surface accepts.	Send a smaller file.
`405`	The path exists, and it does not accept this HTTP method.	Use a method the operation declares in the API reference.
`415`	The `Content-Type` header names a format the operation does not read.	Send `application/json`.
`429`	The caller sent more requests than the deployment’s rate limit allows.	Read the `Retry-After` header, wait that many seconds, then repeat the request.
`422`	The request does not match the operation’s schema.	Correct each entry in `errors`, then repeat the request.
`422`	The request matches the schema, and a business rule refuses its content.	Read `detail`, correct the request, then send it again.

Server errors

Lender answers a 5xx when the request is sound and the call could not complete. For these statuses detail carries a fixed generic value, so the underlying cause stays inside the service. A 503 covers two conditions: a capability the deployment does not run, and a dependency Lender cannot reach at the moment of the call. A 502 covers a third party that refuses a command Lender forwards to it, such as the registry that records an assignment of receivables.

Status	What it means	What to do
`500`	Lender could not complete the request.	On a read, repeat the request. On a command that moves money, read the resource first, and repeat only if the command did not land. If the status repeats, contact support with the operation, the tenant, and the time of the call.
`502`	The registry Lender forwards to refused the command.	The response does not name the reason. Check the fund’s registry configuration and the command’s data, then issue the command again.
`503`	The deployment does not run the capability the operation needs.	Ask your platform team to enable the capability for your deployment.
`503`	A store or a downstream dependency was unreachable.	Retry with backoff.

Brazil loan products

Consignado operations

Loan product lifecycle

Product configuration

Loan Applications

Regulatory disclosures and risk

Payoff and prepayment

Account overview and audit

Charges and schedule

Repayments

Transactions

Accounting

Jurisdictions

Tax

Error handling

Events

Lender error list

Client errors

Server errors

​Client errors

​Server errors

Client errors

Server errors