Errors

Every error we return has the same shape and a stable, machine-readable code. Branch on the code, show your user something friendly, log the trace id, and consult the catalog below for the exact action. That’s the whole game.

The error envelope

Every error response, validation, auth, not found, rate limit, or a bank-side failure, carries the same JSON body under error:

{
  "error": {
    "code": "not_found",
    "message": "No client matches id 'cli_deadbeef'.",
    "type": "not_found",
    "doc_url": "https://portal.ledgersyncappv2.com/errors/not_found",
    "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

Field	What it’s for
`code`	Stable, machine-readable. Branch on this.
`message`	Human-readable explanation. Good for logs; safe for developers, not always for end users.
`type`	Stripe-style class derived from HTTP status: `auth_error`, `invalid_request`, `not_found`, `idempotency_error`, `rate_limit_error`, `api_error`. Coarse grouping only.
`category`	Plaid-style class by origin: `AUTH_ERROR`, `INSTITUTION_ERROR`, `CAPABILITY_UNAVAILABLE`, `CONNECTION_ERROR`, `RATE_LIMIT`, `INVALID_REQUEST`, `RESOURCE_NOT_FOUND`, `PLATFORM_ERROR`. Orthogonal to `type`; still branch on `code`, not this.
`is_user_actionable`	`true` when the end user (not you) can resolve it, e.g. by re-authenticating in the widget.
`doc_url`	Deep link to the page for this specific code.
`trace_id`	The id of this exact request in our logs. Quote it in support tickets.
`param` / `errors[]`	On `validation_failed`, names the offending field(s).
`source_diagnostic_code`	On bank-side errors, the raw upstream code (`FIN-103`, `MX-DENIED`, `FDE-INTERNAL`). For support triage, not control flow.

Branch on code, never on message and never on type. We reword messages over time, and type is deliberately coarse, several very different codes share type: api_error. The code is the contract.

HTTP status, at a glance

Status	Meaning	Typical fix
`400`	Validation / malformed request	Read `error.message` (and `error.param`), fix the field, retry. Don’t retry unchanged.
`401`	Auth: missing, malformed, or wrong key/signature	Send `Authorization: Bearer sk_test_...`; check the key matches the environment.
`403`	Authenticated but not allowed (scope, unapproved access, billing)	Fix the key’s scope or finish the portal step named in the message.
`404`	Not found or not visible to your key	Confirm the id and its environment.
`405`	Right route, wrong HTTP method	Use the method the API reference documents.
`409`	Conflict (idempotency key reuse, stale `row_version`)	Re-fetch, then retry with fresh token/body.
`422`	Accepted but couldn’t be processed (statement extraction)	Read the operation’s `error.message`; fix the input.
`429`	Rate limit against your quota	Back off with jitter; honor `Retry-After`.
`5xx`	Our side or the bank’s side	Retry with backoff; escalate with the trace id.

Error-code catalog

Every code the API can return. The catalog is also browsable at portal.ledgersyncappv2.com/errors, and each error.doc_url deep-links to one entry.

Authentication & authorization

Code	HTTP	When it fires	What to do
`missing_auth_headers`	401	No `Authorization` header.	Add `Authorization: Bearer sk_...`.
`unknown_api_key`	401	Bearer token matches no key (typo, wrong env, revoked).	Check the value and that the key matches the base URL.
`revoked_api_key`	401	Key was valid but has been revoked/rotated.	Mint a new key in the portal, update config.
`invalid_signature`	401	HMAC signature didn’t match the computed one.	Sign over the raw bytes you send; confirm the current secret. Prefer our signing helper.
`invalid_timestamp`	401	`X-LS-Timestamp` is more than 5 min off our clock.	Fix the machine’s clock (NTP), resend.
`replayed_nonce`	401	`X-LS-Nonce` was already used.	Generate a fresh 16+ byte random nonce per request.
`insufficient_scope`	403	Key authenticated but lacks the scope for this operation.	Grant the scope named in `message`, or mint a key with it.
`access_request_not_approved`	403	Minting a key for an env whose access request isn’t `APPROVED`.	Finish/resubmit the access request for that env in the portal.
`billing_not_configured`	403	Live request with no billing subscription linked.	Add a payment method in the portal (Activate Live → Payment).

Request problems

Code	HTTP	When it fires	What to do
`validation_failed`	400	A field failed schema validation. `error.param` / `error.errors[]` name it.	Fix the named field(s), resubmit.
`invalid_request`	400	Rejected for a non-schema reason (bad state transition, unsupported source, idempotency-key reused with a different body).	Read `message`; use a fresh `Idempotency-Key` if retrying with a changed body.
`method_not_allowed`	405	Right route, wrong HTTP method.	Use the documented method; regenerate clients from the spec.
`idempotency_conflict`	409	Same `Idempotency-Key`, different body/path.	Reuse the exact original body to retry, or a new key for a new request.
`version_conflict`	409	Write carried a stale `row_version` (someone else moved the row).	Re-fetch to get the current `row_version` and state, then retry if still needed.
`read_only_client`	403	The target Client is read-only — an aliased/linked pre-existing v2 client. Writes and connection mutations are rejected.	Only mutate native `cli_` clients; treat aliased linked clients as read-only.
`billing_managed_externally`	409	A billing action was attempted on a customer whose billing is managed outside the API.	Manage that customer’s billing through the configured external flow, not the API.
`not_found`	404	No resource matches the id, or it belongs to another customer.	Verify the id (stored the `cli_...`, not your `external_id`?).
`statement_extraction_failed`	422	A `statement.extract` operation finished `failed` (bad scan, not a statement, corrupt pages). Arrives inside the polled operation’s `error`, not as a direct HTTP response.	Fix the document (clearer scan, all pages, real bank PDF) and re-`POST /v3/statements/extract`.

Rate limit

Code	HTTP	When it fires	What to do
`rate_limit_exceeded`	429	More requests than the per-key limit. `X-RateLimit-Reset` / `Retry-After` describe the window.	Back off and retry after `Retry-After`; batch or ask support for a higher quota.

Server

Code	HTTP	When it fires	What to do
`internal_error`	500	Something broke on our side (usually transient).	Retry once with backoff; escalate with the `trace_id`.
`upstream_unavailable`	502	A service v3 depends on (the main LedgerSync backend behind the bridge) is unreachable. Distinct from `source_internal_error`, our platform leg, not the aggregator.	Retry with exponential backoff; escalate with the `trace_id` if it persists.

Connection & source errors (the bank side)

These come back on connection operations, most often inside the polled operation’s error, with the raw upstream code in error.source_diagnostic_code. All carry type: api_error and HTTP 502, so you must branch on code, not on type. They group cleanly by the action they require:

The wire error.category is too coarse to branch on. CAPABILITY_UNAVAILABLE covers agreement_required, statements_not_supported, and fde_unsupported; CONNECTION_ERROR covers both mfa_required and reauthorization_required. Always switch on error.code.

Send the end user back through the widget (re-authenticate):

Code	When it fires
`credentials_invalid`	Bank rejected the login (changed password, re-enrolled creds). `FIN-103/185/948`, `MX-DENIED`.
`mfa_required`	Bank is challenging for a second factor. `FIN-187`, MX `CHALLENGED/MFA_REQUIRED`, FDE `USER_ACTION`.
`mfa_expired`	User didn’t answer the MFA challenge in time. MX `EXPIRED/MFA_EXPIRED`.
`reauthorization_required`	Saved session invalid; bank wants re-consent. MX `CREDENTIALS_UPDATE_REQUIRED` / `USER_INTERACTION_REQUIRED`.
`agreement_required`	Bank needs a new agreement/consent accepted. `FIN-38006`, `MX-AGREEMENT_REQUIRED`.

Don’t re-auth, retry with backoff (credentials are fine):

Code	When it fires
`institution_unavailable`	Bank is down/impaired/transient. Finicity `931/946/990-998`, MX `SITE_DOWN/IMPAIRED`, FDE `INSTITUTION_DOWN`. Show “your bank is having issues,” retry minutes-to-hours later.
`source_rate_limited`	Aggregator/bank throttled back-to-back pulls. `FIN-947`. Back off; don’t tighten your loop.
`source_internal_error`	Aggregator returned a generic internal failure. Untranslated `FIN-`, `-INTERNAL`, `MX-UNKNOWN`. Small retry budget (2–3), then escalate.

Don’t retry, the capability isn’t there:

Code	When it fires
`statements_not_supported`	Institution doesn’t expose statements. `FIN-6004`. Hide “view statements”; transactions/balances still work.
`fde_unsupported`	FDE-backed connection doesn’t expose this capability. Gate the feature by connection source.

User must act at the bank (not in your widget):

Code	When it fires
`account_locked_by_institution`	Bank locked the account (too many attempts / fraud hold). `FIN-109`, `MX-LOCKED`. Tell the user to unlock with their bank; re-auth won’t help.

A handling pattern

The same steps work in any language: check the status, parse the envelope, branch on code, log the trace id.

import requests

resp = requests.post(
    "https://api-sandbox.ledgersyncappv2.com/v3/clients/cli_01HXYZ/connections",
    headers={"Authorization": "Bearer sk_test_..."},
    json={"institution_id": "ins_0a01a5430925d0b2"},
)

trace_id = resp.headers.get("X-LS-Trace-Id")

if resp.ok:
    operation = resp.json()
else:
    err = resp.json()["error"]
    log.warning("LedgerSync code=%s status=%s trace=%s",
                err["code"], resp.status_code, trace_id)

    code = err["code"]
    if code in ("credentials_invalid", "mfa_required", "mfa_expired",
                "reauthorization_required", "agreement_required"):
        send_user_back_through_widget(...)      # re-auth
    elif code in ("institution_unavailable", "source_rate_limited",
                  "source_internal_error", "upstream_unavailable"):
        retry_with_backoff(...)                 # credentials are fine
    elif code == "not_found":
        ...                                     # fix the id
    elif resp.status_code == 401:
        ...                                     # bad key — don't retry
    elif resp.status_code == 429:
        backoff_and_retry(...)                  # see Rate limiting

const resp = await fetch(
  "https://api-sandbox.ledgersyncappv2.com/v3/clients/cli_01HXYZ/connections",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer sk_test_...",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ institution_id: "ins_0a01a5430925d0b2" }),
  }
);

const traceId = resp.headers.get("X-LS-Trace-Id");

if (!resp.ok) {
  const { error } = await resp.json();
  console.warn(`LedgerSync code=${error.code} status=${resp.status} trace=${traceId}`);

  const reauth = ["credentials_invalid", "mfa_required", "mfa_expired",
                  "reauthorization_required", "agreement_required"];
  const retry = ["institution_unavailable", "source_rate_limited",
                 "source_internal_error", "upstream_unavailable"];

  if (reauth.includes(error.code)) sendUserBackThroughWidget();
  else if (retry.includes(error.code)) retryWithBackoff();
  else if (error.code === "not_found") { /* fix the id */ }
  else if (resp.status === 401) { /* bad key — don't retry */ }
  else if (resp.status === 429) backoffAndRetry();
}

Rate limiting

A 429 (rate_limit_exceeded) just means slow down. Use exponential backoff with jitter, and honor Retry-After when present.

import time, random

def call_with_backoff(do_request, max_attempts=5):
    for attempt in range(max_attempts):
        resp = do_request()
        if resp.status_code != 429:
            return resp
        wait = float(resp.headers.get("Retry-After", (2 ** attempt))) + random.random()
        time.sleep(wait)
    return resp  # give up; log the trace id and escalate

async function callWithBackoff(doRequest, maxAttempts = 5) {
  let resp;
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    resp = await doRequest();
    if (resp.status !== 429) return resp;
    const retryAfter = Number(resp.headers.get("Retry-After")) || 2 ** attempt;
    await new Promise((r) => setTimeout(r, retryAfter * 1000 + Math.random() * 1000));
  }
  return resp; // give up; log the trace id and escalate
}

The same backoff is the right response to 5xx and the retryable bank-side codes above. Only non-429 4xx errors mean “don’t retry until you change something.”

The trace id

Every response, success or error, includes an X-LS-Trace-Id header (also mirrored as error.trace_id in error bodies):

X-LS-Trace-Id: 7b3f9c2a1e4d40a8b6c0f1e2d3a4b5c6

Log it on every request, even successful ones. When something looks wrong downstream (“this account has no transactions”), the trace id from the original read is what we need.

Getting help

When you file a ticket, include: the X-LS-Trace-Id (or error.trace_id), the error.code, the endpoint, and whether you were in sandbox or live. That’s everything we need to find your exact request.

Testing in sandbox

Reproduce every error path on purpose with sandbox test banks.

Connection lifecycle

Most bank-side codes surface as a connection.failed transition.

Get started

Guides

Go live

The error envelope

HTTP status, at a glance

Error-code catalog

Authentication & authorization

Request problems

Rate limit

Server

Connection & source errors (the bank side)

A handling pattern

Rate limiting

The trace id

Getting help

Testing in sandbox

Connection lifecycle

​The error envelope

​HTTP status, at a glance

​Error-code catalog

​Authentication & authorization

​Request problems

​Rate limit

​Server

​Connection & source errors (the bank side)

​A handling pattern

​Rate limiting

​The trace id

​Getting help

Testing in sandbox

Connection lifecycle

The error envelope

HTTP status, at a glance

Error-code catalog

Authentication & authorization

Request problems

Rate limit

Server

Connection & source errors (the bank side)

A handling pattern

Rate limiting

The trace id

Getting help