Error Codes
Errors are returned in the common error envelope. Branch on code, not on message; envelope fields and general rules: Error Handling.
{
"status": "failure",
"code": "bank_connect.validation.invalid",
"message": "The bank connection request is invalid — see `details.errors`.",
"statusCode": 400,
"requestId": "00000000-0000-0000-0000-000000000000",
"details": {
"errors": [{ "field": "bookedTo", "reason": "range_too_large" }]
}
}Summary
For money transfers and currency exchange, outcomes decided at the bank are not HTTP errors; they are in the record's failureCode: Transfer result codes · Exchange result codes.
Code reference
bank_connect.validation.invalid
The request breaks one of this product's rules. The reason is in details.errors[]: each item carries field and reason. Common reasons on the transaction list:
reason | Cause |
|---|---|
booked_from_required | bookedTo is present, bookedFrom is not. |
after_booked_to | bookedFrom is after bookedTo. |
range_too_large | The date range is longer than 92 days. |
min_greater_than_max | minAmountMinor is greater than maxAmountMinor. |
invalid | The value could not be read. |
On transfer and exchange requests, field names the field in snake case (receiver_iban, amount_minor …):
field | reason | Cause |
|---|---|---|
receiver_iban | required, invalid | No IBAN, or the TR IBAN check digits do not match. |
receiver_name | required, length, invalid_characters | No receiver name, outside 2–140 characters, or a character that is not allowed. |
amount_minor | must_be_positive_integer | The amount is not an integer greater than zero. |
currency | invalid | The currency is not a three-letter ISO 4217 code. |
payment_purpose | invalid | The payment purpose code is malformed. |
description | too_long, invalid_characters | The description is longer than 140 characters or has a character that is not allowed. |
target_account_id | same_as_source | The exchange quote's source and target accounts are the same. |
amount | exactly_one_of_source_or_target | The exchange quote has both amounts or neither. |
Fix the request and send it again. → Transactions › Date range rules
bank_connect.cursor.invalid
The pagination cursor was not recognised. Do not build or alter cursors; send the pageInfo.nextCursor value from the previous response verbatim. If you changed filters, reset the cursor and start from the first page. → API Introduction › Pagination
bank_connect.connection.not_found
Connection not found. The ID is wrong or malformed, the record belongs to another organization, or it is not in your key's environment. A test key does not see live connections and a live key does not see test connections.
bank_connect.account.not_found
Account not found. Check the ID and your key's environment. Get account IDs from the Accounts endpoint.
bank_connect.transaction.not_found
Transaction not found. Check the ID and your key's environment. Get transaction IDs from the Transactions endpoint or from data.transactionId in the webhook.
bank_connect.connection.not_active
The Sync Now request was not accepted because the account's connection is not in a readable state. Syncing is only done for ACTIVE and DEGRADED connections. Check the connection status with the Connections endpoint; what the status means and what to do: Concepts › Connection statuses.
bank_connect.internal.integrity
The request could not be completed on the server side; there is nothing to fix in your request. Retry with exponential backoff. If the problem persists, contact support with the requestId from the response.
Money movement — IP allowlist codes
bank_connect.auth.ip_allowlist_required
Money movement endpoints (bank-connect:transfer) need an API key with an IP allowlist; your key's list is empty. Add your server's outbound IP addresses to the key in the panel. → API Introduction › IP allowlist
bank_connect.auth.ip_not_allowed
The request came from an IP address that is not on the key's allowlist. If your server's outbound address changed (new server, NAT, load balancer), update the list. Changes take effect within 15 seconds.
bank_connect.auth.ip_allowlist_unavailable
The IP allowlist could not be verified right now, so the request was refused for safety. Nothing in your request needs fixing; retry the same request (same Idempotency-Key) with backoff.
Money transfer codes
bank_connect.transfer.not_found
Transfer not found. The id is wrong or malformed, the record belongs to another organization, or it is not in your key's environment.
bank_connect.transfer.capability_unavailable
Money transfers are not available on this connection. The connection's capabilities must include OUTGOING_TRANSFER. → Connections
bank_connect.transfer.account_not_eligible
No transfer or exchange can be made from this account right now. details.reason gives the cause: account_inactive (the account is not active), connection_not_active (the connection is not ACTIVE or DEGRADED), credential_not_active (the details your bank gave are invalid; update them in the panel).
bank_connect.transfer.invalid_state
The transfer is not in a state that allows this operation (for example a pending transfer was already confirmed or canceled). Read the transfer's current status.
bank_connect.transfer.idempotency_conflict
This Idempotency-Key was already used with a different body. When resending the same transfer keep the body identical; use a new key for a new transfer.
bank_connect.transfer.idempotency_key_required
Creating a transfer or an exchange order requires the Idempotency-Key header. → Money Transfers › Idempotency-Key
bank_connect.transfer.idempotency_key_invalid
The Idempotency-Key must be 8–200 printable ASCII characters, without spaces or non-ASCII letters.
bank_connect.transfer.currency_unsupported
Transfers are not supported in this currency. Only TRY transfers are possible today; send currency as TRY or leave it out.
Currency exchange codes
bank_connect.fx.quote_not_found
Exchange quote not found. Check the quote id and your key's environment.
bank_connect.fx.quote_expired
The quote has expired. Get a new quote and open the order before it expires. If the quote expires after the order was opened but before it reached the bank, the order becomes FAILED with this code in failureCode.
bank_connect.fx.quote_used
An order was already opened with this quote; a quote serves one order. When resending the same order, use the same Idempotency-Key.
bank_connect.fx.order_not_found
Exchange order not found. Check the id and your key's environment.
bank_connect.fx.pair_unsupported
The bank does not exchange between these two currencies.
bank_connect.fx.accounts_invalid
The accounts are not valid for an exchange: the source and target accounts must be active, on the same connection and in different currencies. The cause is in details.reason.
bank_connect.fx.capability_unavailable
Currency exchange is not available on this connection. The connection's capabilities must include FX_EXCHANGE.
bank_connect.fx.invalid_state
The exchange order is not in a state that allows this operation. Read the order's current status.
bank_connect.fx.idempotency_conflict
This Idempotency-Key was already used with a different body. Use a new key for a new order.
bank_connect.fx.quote_rejected
The bank did not give a quote. The cause in details.reasonCode is an exchange result code (for example bank_connect.fx.market_closed, bank_connect.fx.below_minimum, bank_connect.fx.limit_exceeded). Change the amount or try later, depending on the cause.
Panel verification codes
The codes below appear only for transfers and exchanges made in the panel, at the e-mail verification step. Requests made with an API key have no verification code.
bank_connect.transfer.actor_mismatch
In the panel, only the user who started the transfer or the exchange session can confirm it.
bank_connect.transfer.otp_invalid
The e-mail verification code is incorrect.
bank_connect.transfer.otp_expired
The verification code or the confirmation window has expired; request a new code. A panel transfer that is not confirmed in time is canceled with this code in failureCode.
bank_connect.transfer.otp_resend_limited
Wait before asking for a new code: codes are sent at least 30 seconds apart and at most 5 times per operation.
bank_connect.transfer.step_up_unavailable
The verification code cannot be sent right now; try again shortly.
bank_connect.transfer.step_up_actor_required
This operation is done by a panel user; refresh your panel session and try again.
bank_connect.fx.session_required
In the panel, confirm the e-mail verification code and open an exchange session before getting a quote or opening an order.
bank_connect.fx.session_not_found
Exchange session not found; start again with Exchange currency.
bank_connect.fx.session_expired
The 5-minute exchange session has expired; it is not extended. Request a new code to open a new session.
bank_connect.fx.session_invalid_state
The exchange session is not in a state that allows this operation (for example the code is not confirmed yet, or was already confirmed).
bank_connect.fx.session_scope_mismatch
The exchange session was opened for another bank connection; open a new session for this connection.
Transfer result codes
These codes are not returned as HTTP errors; they are in the failureCode of a FAILED, RETURNED or CANCELED transfer and in the bank_transfer.failed / bank_transfer.returned webhook. The request that creates the transfer answers 201; the outcome comes later.
bank_connect.transfer.insufficient_balance
Insufficient account balance.
bank_connect.transfer.limit_exceeded
The transfer limit at the bank is exceeded or not defined. Check your limit with your bank.
bank_connect.transfer.eft_cutoff_passed
The EFT cut-off time has passed; send the transfer again on the next business day.
bank_connect.transfer.invalid_amount
The bank rejected the amount.
bank_connect.transfer.invalid_request
The bank rejected the transfer request as invalid.
bank_connect.transfer.invalid_payment_purpose
The payment purpose is invalid; pick a code from the payment purposes endpoint.
bank_connect.transfer.receiver_name_mismatch
The receiver name does not match the IBAN holder. Write the IBAN holder's name or title exactly.
bank_connect.transfer.receiver_bank_not_supported
The receiving bank does not support this transfer type.
bank_connect.transfer.rejected_by_bank
The bank rejected the transfer; contact your bank for details.
bank_connect.transfer.canceled_by_user
The transfer was canceled in the panel.
bank_connect.transfer.canceled_by_bank
The transfer was canceled by the bank.
bank_connect.transfer.returned_by_bank
The completed transfer was returned by the receiving bank; the transfer becomes RETURNED.
bank_connect.transfer.outcome_unknown
The transfer outcome could not be confirmed with the bank; Lunixi is checking it. Do not send the transfer again.
bank_connect.transfer.failed_after_bank_check
The outcome was checked with the bank: the transfer did not take place. You can send the payment again with a new Idempotency-Key.
Exchange result codes
These codes are in the failureCode of a FAILED exchange order and, when a quote is refused, in the details.reasonCode of bank_connect.fx.quote_rejected.
bank_connect.fx.insufficient_balance
Insufficient balance in the source account.
bank_connect.fx.below_minimum
The amount is below the bank minimum.
bank_connect.fx.limit_exceeded
The daily or monthly exchange limit at the bank is exceeded.
bank_connect.fx.market_closed
The exchange market is closed right now (for example at the weekend); try again when it is open.
bank_connect.fx.invalid_request
The bank rejected the exchange request as invalid.
bank_connect.fx.rejected_by_bank
The bank rejected the exchange.
bank_connect.fx.outcome_unknown
The exchange outcome could not be confirmed with the bank; Lunixi is checking it. Do not open the order again.
bank_connect.fx.failed_after_bank_check
The outcome was checked with the bank: the exchange did not take place. You can get a new quote and open a new order.
Common codes
The following platform codes may also be returned by these endpoints. Their meaning and solutions are on the shared pages:
code | HTTP | Where |
|---|---|---|
VALIDATION_ERROR | 400 | Undeclared parameter, invalid filter value, limit outside 1–100. → Error Handling |
AUTH_HEADERS_MISSING, INVALID_SIGNATURE, NONCE_REPLAY, INVALID_DATE | 401 | Signature headers missing or the signature could not be verified. → Error Handling |
PRODUCT_NOT_ENABLED | 403 | The key does not carry the Bank Connections product. → Error Handling |
API_INSUFFICIENT_SCOPE | 403 | The key does not carry the endpoint's permission (bank-connect:transfer on money movement endpoints). → API Introduction › Permissions |
RATE_LIMITED | 429 | The sync now or money movement request limit was exceeded. → Limits |
The codes on this page may grow over time. Handle an unknown bank_connect.* code by its HTTP status: do not retry 4xx without changing the request, retry 5xx with backoff.