Errors

The API returns structured errors with stable codes. Branch on the code field, not the human-readable message.

Error envelope

Any non-2xx response has the following body:

{
  "code": "not_found",
  "sub_code": "customer_not_found",
  "message": "lms: status=404: Customer with id 9999 does not exist"
}

The HTTP status always matches the code. The message is a human-readable string scoped to the partner contract — internal LMS vocabulary (Client, globalisation codes like error.msg.*) is rewritten or stripped before it reaches the wire, and it may change, so don’t parse it. code is an error-only field: successful responses return the resource object (no code), and 204 No Content has no body. Some errors also carry an optional sub_code — a stable, finer-grained business reason within a code. It lets you map an error to a specific customer-facing message without parsing message (see Sub-codes below). sub_code is additive and optional: an error may omit it, and new sub-codes may be introduced over time — so always branch on code first, and treat an unknown or absent sub_code by falling back to the code. For validation failures (invalid_argument), the message is a JSON-encoded array of {field, error} pairs:

{
  "code": "invalid_argument",
  "sub_code": "validation_error",
  "message": "[{\"field\":\"principal\",\"error\":\"must be greater than 0\"}]"
}

Error codes

These are the codes the API currently returns. Branch on code.

HTTP	`code`	When
400	`invalid_argument`	Malformed or invalid input regardless of state — a malformed request body, missing/empty/non-positive field, a date not in `yyyy-MM-dd`, a value too long. Field-validation failures list the offending fields in `message` (see above).
400	`failed_precondition`	The resource is in the wrong state for the operation — e.g. updating/deleting/adjusting an already-disbursed loan, or repaying a non-active loan. Fix the state first.
401	`unauthenticated`	Missing, expired, or invalid bearer token. Refresh the token and retry.
403	`permission_denied`	Authenticated, but the caller’s role isn’t authorized for this action. Refreshing the token won’t help.
404	`not_found`	No resource exists with that id or externalId.
409	`already_exists`	A uniqueness constraint was violated — a re-used `externalId` on a customer, loan, or repayment (`idempotencyKey`).
409	`aborted`	Conflict — a concurrency issue, or an operation blocked by the resource’s current state (e.g. rolling back a loan that already has repayments).
500	`internal`	Unexpected server-side or upstream failure. Detail is withheld from the response and logged.
503	`unavailable`	A downstream dependency (core banking / credit service) is temporarily unreachable.

Reserved codes (not currently emitted)

The error vocabulary also defines the canonical codes below, which the API does not currently return. They’re documented so your handler recognises them if a future version starts using one — you don’t need to handle them today. Your code fallback (treat any unrecognised code as a non-retryable error and surface it) covers them safely.

HTTP	`code`	Reserved meaning
400	`out_of_range`	A value is outside the valid range — distinct from `invalid_argument` in that validity depends on current state (e.g. paging past the end of a result set).
429	`too_many_requests`	Emitted. You are over your per-caller rate, or the platform is at capacity. The response carries `Retry-After` (seconds); wait that long and retry. Safe for every call — a repayment that was refused with 429 was never posted, so re-sending it with the same `idempotencyKey` is exact.
429	`resource_exhausted`	Reserved: quota exceeded.
501	`unimplemented`	The operation is not supported.
504	`deadline_exceeded` / `canceled`	The request timed out or was canceled upstream. Would be retryable.

Sub-codes

When present, sub_code pins down the exact business scenario behind the code. Each maps cleanly to a fixed customer-facing message — only validation_error requires reading message (for the per-field detail). Branch on code first; use sub_code to refine the message you show.

`code`	`sub_code`	Meaning
`invalid_argument`	`validation_error`	Request failed field validation — ours (the offending fields are in `message` as a `[{field, error}]` array) or the LMS’s (a `principal` outside the product’s min/max, an unknown `closureReasonId`; the LMS’s field message is in `message`).
`already_exists`	`customer_external_id_exists`	The customer `externalId` is already in use.
`already_exists`	`loan_external_id_exists`	The loan `externalId` is already in use.
`already_exists`	`transaction_external_id_exists`	The repayment `idempotencyKey` is already recorded on a different transaction.
`not_found`	`customer_not_found`	No customer exists for the given id/externalId.
`not_found`	`loan_not_found`	No loan exists for the given id/externalId.
`not_found`	`product_not_found`	No loan product exists for the given id.
`not_found`	`transaction_not_found`	No repayment transaction with that id exists on the loan.
`failed_precondition`	`loan_not_active`	A repayment was attempted on a loan that isn’t active.
`failed_precondition`	`loan_no_disbursement`	An operation needing a disbursement (e.g. adjusting the disbursement date) was attempted on a loan that has none.
`failed_precondition`	`boost_not_eligible`	The customer isn’t eligible for a credit-limit boost.
`failed_precondition`	`domain_rule_violation`	A business rule blocked the operation given the entity’s current state (e.g. modifying an already-disbursed loan, closing a customer that still has active loans, a value date before disbursement). The specific reason is in `message`.
`aborted`	`rollback_has_repayments`	A loan rollback was blocked because the loan already has repayments — reverse them first.
`aborted`	`adjust_has_repayments`	A disbursement-date adjustment was blocked because the loan already has repayments — reverse them first.
`failed_precondition`	`loan_not_overpaid`	A refund was attempted on a loan carrying no overpayment credit — either it was never overpaid, or the credit has already been refunded.
`aborted`	`adjust_has_penalty`	A disbursement-date adjustment was blocked because an overdue penalty has already been posted to the loan — waive or reverse it first.
`aborted`	`loan_not_rollbackable`	The loan’s status doesn’t permit a rollback (rollback is for tearing down a loan that never reached the customer, not a settled one).
`permission_denied`	`insufficient_role`	The authenticated caller’s role isn’t permitted to perform the action.

Idempotency (repayments)

Repayments accept an optional idempotencyKey (your wallet transaction reference). Re-sending the same key on the same loan returns the original transaction with 200 — a safe replay, not an error. Re-using a key already recorded elsewhere (a different loan, or a race) returns already_exists (409).

Retrying

Code	Retry?
`too_many_requests`	Yes — after the `Retry-After` seconds in the response. Nothing was executed, so a repayment can be re-sent with the same `idempotencyKey` without reconciling.
`unavailable`	Yes, with backoff. For non-idempotent calls (e.g. repayments), reconcile first.
`internal`	Yes once for idempotent calls, then surface to the caller.
`unauthenticated`	No — refresh the token, then retry once.
`permission_denied`, `invalid_argument`, `failed_precondition`, `not_found`, `already_exists`, `aborted`	No — client-side fix; surface to the caller.

too_many_requests (429) is returned when a caller exceeds its rate or the platform is at capacity: honour Retry-After, then retry. The other reserved codes aren’t returned today; if introduced, resource_exhausted and deadline_exceeded would be retryable with backoff.

Example: branching on errors

import json, requests

resp = requests.post(f"{BASE}/v1/customers", json=payload,
                     headers={"Authorization": f"Bearer {token}"})

if resp.ok:
    customer = resp.json()
else:
    err = resp.json()
    code = err["code"]
    sub = err.get("sub_code")            # optional, finer-grained
    if code == "invalid_argument":
        for fe in json.loads(err["message"]):
            print(f"  {fe['field']}: {fe['error']}")
    elif code == "already_exists" and sub == "customer_external_id_exists":
        show_customer("This ID is already registered")
    elif code == "unauthenticated":
        refresh_token_and_retry()
    elif code in ("unavailable", "deadline_exceeded", "internal"):
        retry_with_backoff()
    else:  # branch on `code`; refine the message with `sub` when present
        raise RuntimeError(f"{code}/{sub}: {err['message']}")

Getting Started

Concepts

Customers

Loans

Repayments

Loan Products

Credit Scoring

Error envelope

Error codes

Reserved codes (not currently emitted)

Sub-codes

Idempotency (repayments)

Retrying

Example: branching on errors

​Error envelope

​Error codes

​Reserved codes (not currently emitted)

​Sub-codes

​Idempotency (repayments)

​Retrying

​Example: branching on errors

Error envelope

Error codes

Reserved codes (not currently emitted)

Sub-codes

Idempotency (repayments)

Retrying

Example: branching on errors