Guides

Errors

Every failed response has the same body, with a code that says what happened and who has to act. Branch on the code, never on the wording.

The error body

A sandbox connection made as user_expires_at_sync stops at its first sync, and every sync after that answers this:

409 Conflict

{
  "detail": "Unattended sign-in for this connection was stopped at 2026-10-21 01:01 UTC after a sign-in did not complete (session_expired). Nothing further will be attempted against the institution; the user must reconnect.",
  "error": {
    "code": "session_expired",
    "message": "Unattended sign-in for this connection was stopped at 2026-10-21 01:01 UTC after a sign-in did not complete (session_expired). Nothing further will be attempted against the institution; the user must reconnect.",
    "retryable": false,
    "request_id": "req_1b53be0b41aa8d3237e6b6c3",
    "type": "connection_error",
    "user_action": "reconnect",
    "display_message": "Your AlkiraiLink Sandbox Bank sign-in has expired. Reconnect to keep your accounts up to date.",
    "retry_after": null,
    "stopped_at": "2026-10-21T01:01:17Z"
  }
}

• error.code is what to branch on. The full list is below.
• error.user_action is what the person has to do: reconnect, contact_institution, sign_in or none.
• error.display_message is a sentence you can show the person, when there is one. Never show them message or detail, which are for you.
• error.retryable says whether the same request can succeed later with nobody doing anything. When it is false, asking again only repeats the answer.
• error.request_id is also in the X-Request-Id header. Quote it when you write to us.

detail repeats message, except on a 422 for the request's shape, where it lists each field that didn't match.

Retrying

• Retry only when retryable is true, and no sooner than retry_after seconds when it is set.
• Back off between tries. A read can spend a sign-in, and an institution's budget is small: see Syncing and budgets.
• Never retry invalid_credentials. Repeated wrong passwords lock accounts, and AlkiraiLink stops the connection so that nothing does.
• More than 120 requests a minute from one address is refused with a 429 before it reaches the API. That one has no JSON body: wait a minute.

Statuses

Codes

Each code's type and the person's action never change, so you can map them once. Retry says whether asking again later can help.