Errors and status codes

This page is the consolidated reference for the response envelopes used by every route on the loan-domain API. Per-route documentation lists the status codes a specific route emits; this page documents the shape of each envelope and the catalogue of named code values you may receive.

Read it once before integrating; refer back whenever a non-2xx status surprises you.

Status-code catalogue

Treat any 4xx other than 429 as a request defect — your client logic should reject the input rather than retry. Treat 429 and 500 as transient and retry with backoff; an Idempotency-Key makes the retry safe.

Standard envelopes

The loan-domain API uses three response envelopes for non-success status codes. The shape of the envelope tells you what kind of failure you are looking at.

Validation envelope — 400 Bad Request

Used for schema violations, malformed query parameters, and malformed paths.

{
  "error": "Validation failed",
  "fieldErrors": [
    { "path": "interestRateApr", "message": "interestRateApr must be >= 0" },
    { "path": "termMonths", "message": "termMonths must be > 0" }
  ]
}

Some routes emit errors[] rather than fieldErrors[] for query-parameter failures (the framework convention varies by surface). The path/message shape is identical; treat the two array names as interchangeable for parsing purposes.

Named-code envelope — 4xx

Used when the failure has a specific cause the platform names with a stable code value. The presence of fieldErrors is optional and depends on whether the failure can be attributed to a specific field.

{
  "error": "a borrower with this id already exists",
  "code": "ID_CONFLICT",
  "fieldErrors": [
    { "path": "id", "message": "a borrower with this id already exists" }
  ]
}

Some envelopes carry additional structured context — for example batch_too_large includes a fieldErrors block naming the cap exceeded. The per-route documentation names these.

Bare-error envelope — 404 / 401

Used for terse responses where no additional context would help the caller. 404 is the typical example:

{ "error": "Not found" }

Some routes return { "error": "...", "code": "NOT_FOUND" }; treat the presence or absence of code on a 404 as informational, not load-bearing.

Two codespaces: upper-case vs lower-case

The loan-domain API uses two distinct code namespaces, intentionally separated by ingestion shape:

• Single-record routes (POSTs, PATCHes, the cancel and the reconciliation GETs) emit UPPER_CASE code values: ID_CONFLICT, PORTFOLIO_NOT_FOUND, REFERENCED_ENTITY_NOT_FOUND, INVALID_STATUS_TRANSITION, CHECK_VIOLATION, NOT_FOUND, UNKNOWN_KIND, COMMIT_FAILED.
• Bulk NDJSON routes emit lower_case code values: batch_too_large, portfolio_not_found, portfolio_id_required, invalid_body, invalid_json, plus the per-row codes documented below.

When you branch on code in your client, match the exact case. The two codespaces are stable separately; do not normalise them.

Error-code glossary

The platform attaches a stable code to every named failure mode. Use these for programmatic branching; the error message text may evolve.

Single-record codespace

Bulk-NDJSON codespace

A code that is not in this glossary indicates the platform added a new named code since this page was last revised. Always log the code value verbatim alongside your application's error so the engineering team can correlate.

Per-row error codes (bulk and async imports)

Bulk NDJSON and async imports both return per-row errors. The bulk surface uses one set of values; the async-imports surface uses a similar but slightly different set (notably it includes validation_error rather than validation_failed, reflecting an older surface). Per-row entries describe individual row failures inside a successful batch, not envelope failures.

Bulk NDJSON per-row codes

Async imports per-row codes

Database-level errors during the silver insert step (FK violations, unique violations, CHECK violations) are wrapped by the silver normalisation worker and surface under one of the codes above with the database detail folded into errorMessage.

Per-row errors never bubble to a top-level non-200 response from the bulk surface — the batch as a whole succeeded if the request itself was well-formed; the per-row codes tell you what landed.

Retry semantics

A retry-safe pattern for any mutating route is:

1. Generate a deterministic Idempotency-Key per logical operation. A UUIDv4 plus a route discriminator works.
2. Send the request with the key.
3. On any of 2xx, 409 ID_CONFLICT, 404, 400, or 413 — do not retry. The outcome is final.
4. On 429 — retry after the duration in the Retry-After header.
5. On 500 or a network error — retry up to a small fixed number of times with exponential backoff. The Idempotency-Key makes the retry safe whether or not the first attempt landed.

A retry of a successful request with the same Idempotency-Key returns the same response as the original, with reused: true on the affected entity. This is the canonical happy-path recovery from a network blip.

What the platform never returns

For operational debugging, it is useful to know the negative space:

• No 5xx status code is treated as a feature by the platform. A 500 is always a bug to be fixed; never write client logic that depends on a specific 500 shape.
• No 404 response leaks tenancy. A 404 on a row that exists in another organisation looks identical to a 404 on a row that does not exist anywhere. Do not write client logic that infers cross-tenant existence.
• No success response carries a body field named success: false. The status code is the source of truth for whether the call succeeded; the body shape carries the detail.
• No write route returns its own UUID in a path-parameter style ("Location" header). The created UUID appears in the response body's id field.