Handled Errors

Flinks Connect handles several common authentication and connection errors automatically, displaying user-friendly messages to your customers. Each error triggers a corresponding JavaScript event that you can capture with an Event Listener.

Error types

Error Event	HTTP Code	Flinks Code	Description	User Action
`INVALID_USERNAME`	401	`INVALID_USERNAME`	The username provided was different from what the bank expected.	Customer should re-enter their username.
`INVALID_PASSWORD`	401	`INVALID_PASSWORD`	The password provided was different from what the bank expected.	Customer should re-enter their password.
`INVALID_LOGIN`	401	`INVALID_LOGIN`	The provided credentials are incorrect.	Customer should verify and re-enter their login details.
`INVALID_SECURITY_RESPONSE`	401	`INVALID_SECURITY_RESPONSE`	The MFA response provided was different from what the bank expected.	Customer should try answering the security question again.
`RETRY_LATER`	401	`RETRY_LATER`	Flinks was unable to open a connection with the financial institution.	Customer should try again later.
`UNAUTHORIZED`	401	`UNAUTHORIZED`	The institution did not authorize access.	Customer may need to complete additional steps on their bank’s website.
`NEW_ACCOUNT`	401	`NEW_ACCOUNT`	The customer must take action directly on their online banking before connecting.	Customer should log in to their bank website first (e.g., accept terms).
`AGGREGATION_ERROR`	500	`AGGREGATION_ERROR`	Flinks encountered an unexpected error during processing.	Customer should try again. If the issue persists, contact support.
`DISABLED_INSTITUTION`	405	`DISABLED_INSTITUTION`	The selected financial institution is not currently available.	Customer should try a different institution or try again later.
`DISABLED_LOGIN`	401	`DISABLED_LOGIN`	The account has been deactivated by the financial institution.	Customer must contact their bank to reactivate the account.

Capturing error events

To detect these errors programmatically, add an Event Listener to your Flinks Connect integration:

<script>
  window.addEventListener("message", function (e) {
    const data = e.data;

    // Check for error events
    if (data.flinksCode) {
      switch (data.flinksCode) {
        case "INVALID_USERNAME":
        case "INVALID_PASSWORD":
        case "INVALID_LOGIN":
          // Handle credential errors
          console.log("Credential error:", data.flinksCode);
          break;
        case "INVALID_SECURITY_RESPONSE":
          // Handle MFA error
          console.log("MFA error:", data.flinksCode);
          break;
        case "RETRY_LATER":
        case "AGGREGATION_ERROR":
          // Handle temporary errors
          console.log("Temporary error:", data.flinksCode);
          break;
        case "DISABLED_INSTITUTION":
        case "DISABLED_LOGIN":
        case "NEW_ACCOUNT":
        case "UNAUTHORIZED":
          // Handle account/institution issues
          console.log("Account issue:", data.flinksCode);
          break;
      }
    }
  });
</script>

Testing errors

You can test each error type using the Flinks Capital test institution by changing the username to specific test values. See the full list of test error scenarios. For a complete list of all API error codes (including those not handled by Flinks Connect), see Error Codes.

Getting Started

AI

Connect

Enrich

Pay

Webhooks

Upload

Dashboard

Outbound

Security

Support

Error types

Capturing error events

Testing errors

​Error types

​Capturing error events

​Testing errors

Error types

Capturing error events

Testing errors