Errors & status codes · LendEasy Docs

Handle the Lending Core error envelope, globalisation codes, field-level violations, conflicts, rate limits, and uncertain outcomes without parsing prose.

Lending Core errors are application/json with one envelope. Branch on HTTP status and the stable userMessageGlobalisationCode; display or log the messages safely, but never parse them for program logic. Note that httpStatusCode is a string.

The error envelope

{
  "developerMessage": "Request was understood but rejected; inspect errors for field-level causes.",
  "httpStatusCode": "400",
  "defaultUserMessage": "The request could not be applied.",
  "userMessageGlobalisationCode": "validation.msg.validation.errors.exist",
  "errors": [
    {
      "developerMessage": "stateCode must be a full ISO 3166-2 code matching country.",
      "defaultUserMessage": "stateCode is invalid.",
      "userMessageGlobalisationCode": "validation.msg.address.stateCode.invalid",
      "parameterName": "stateCode",
      "value": "CA"
    }
  ]
}

Validation failures carry one errors entry per violating field. Unknown body fields and unknown query parameters are rejected with 400 rather than silently discarded.

Status contract

Status	Meaning	Retry?
`200`	Successful read, or a mutation’s command envelope `{resourceId, changes}`.	No.
`201`	Payment or funding created; `Location` names the new resource.	No — a replayed create returns the original result with `x-served-from-cache: true`.
`400`	Malformed request: unknown field or query parameter, invalid value, or a missing or invalid tenant header.	Fix request.
`401`	Token missing, invalid, expired, or wrong environment.	Refresh once; then stop.
`403`	Authenticated but missing the named permission or case authority.	Change authorization, not request timing.
`404`	Resource absent or outside tenant visibility.	Verify ID and environment.
`409`	Lifecycle-state conflict, an identical idempotent request still in flight (includes `Retry-After`), or a second entry for a SINGLE-mode form.	Read current state — or wait `Retry-After` and resend the same request.
`422`	Well-formed request violates a business rule, including an idempotency payload fingerprint mismatch.	Correct inputs or follow declared review path.
`429`	Current rate budget exceeded.	Honor `Retry-After` with same idempotency key.
`5xx`	Server or dependency failure; outcome may be unknown.	Retry safely with backoff and same key.

Conflict families

Not every 409 means duplicate create:

in-flight idempotency: the same key’s original attempt is still executing; the response carries Retry-After — wait and resend the identical request;
state conflict: the operation is not valid from the resource’s current lifecycle state;
single-entry conflict: a second entry was created for a SINGLE-mode form on the same target.

A reused key with a different payload on a money create is not a 409 — it is a 422 fingerprint mismatch. Read the resource and surface the current state to the workflow; blind retries cannot resolve a semantic conflict.

Business outcome versus HTTP failure

A loan summary read can succeed while reporting that no payoff can be quoted:

{
  "loanRef": "7204",
  "payoff": { "available": false },
  "asOf": "2026-09-20T10:00:00Z"
}

That is 200: the read model worked and the business answer is “not available right now.” Conversely, a 503 means no reliable answer was produced and the caller follows fail-closed degraded behavior.

Servicing Plane contract

Errors under /v1/servicing keep that surface’s application/problem+json shape — type, title, status (numeric), a stable code, detail, and requestId:

{
  "type": "https://docs.lendeasy.ai/errors/state_conflict",
  "title": "State Conflict",
  "status": 409,
  "code": "state_conflict",
  "detail": "The case changed after it was read.",
  "requestId": "req_01J2R8M6YQ3C7K2N"
}

Branch on status and code there, exactly as you branch on status and globalisation code on the Lending Core.

Request correlation

Retain the request correlation identifiers your client and the response headers carry in logs and support reports; the servicing-plane envelope also carries requestId in the body. Do not log bearer tokens, raw personal data, provider credentials, full document payloads, or sensitive error inputs.

Safe retry skeleton

if 429: wait Retry-After + jitter; retry same key
if retryable 5xx/network timeout: exponential backoff; retry same key
if 409 with Retry-After: wait; resend the identical request
if other 409: read current state; make a new business decision
if 422: present the structured rule/field failure; do not loop
if 401: refresh token once
if 400/403/404: stop and fix the request, authorization, or identifier

A network timeout does not prove failure. Treat the outcome as unknown and recover with the same idempotency key or status read; never create a second money movement to “make sure.”