Connection Statuses

A connection started immediately upon initialization in the Create a Connection endpoint. These are the various statuses that a Meld bank linking connection can hold and what they mean:

IN_PROGRESS - A connection is in progress following its initialization and the customer is in the widget flow. It will remain in this status until it becomes either EXPIRED or ACTIVE.
Note: A connection with this status cannot be refreshed nor repaired as it is currently in progress with the customer.
EXPIRED - A connection becomes expired if it was never completed in the allowed timeframe (4 hours) since its initialization.
Note: A connection with this status is terminal and cannot be refreshed nor repaired.
ACTIVE - A connection becomes active once the user successfully completes the widget flow and access to the underlying financial accounts is authorized. The BANK_LINKING_CONNECTION_COMPLETED webhook will indicate once a connection becomes ACTIVE. A connection will remain active indefinitely unless an error occurs during a forced or background refresh, or it is deleted. Following the initial connection, an ACTIVE status does not necessarily imply that the initial aggregation of desired products has completed, but rather that the connection to the underlying institution is complete and aggregation is in progress. The BANK_LINKING_ACCOUNTS_UPDATED webhook will notify of aggregation completion.
Note: A connection with this status is refreshable, but not repairable.
PARTIALLY_ACTIVE - The connection is experiencing temporary issues and cannot be aggregated at this time, but it should resolve on its own. This status may also occur if only some accounts belonging to the connection successfully aggregated, but not all that were requested.
Note: A connection with this status is refreshable, but not repairable.
RECONNECT_AVAILABLE - The connection is active and routinely aggregating, but has the option to reconnect. This may occur for connections in which new accounts were detected and can be added (with customer consent), or when service provider access will expire soon, but the connection will still be operational until then.
Note: A connection with this status is refreshable and repairable.
RECONNECT_REQUIRED - Indicates that a once ACTIVE connection is now failing and needs to be repaired in order to capture the most up to date data. When a connection enters this status, you will be notified via webhooks of the status change. Depending on the cause for error, the connection should be repaired via the repair flow. A common situation that might cause this is if a customer changes their bank password after connecting their accounts, or the underlying service provider consent to the accounts expired. Repairing the connection will make it ACTIVE again.
Note: A connection with this status cannot be refreshed and will not update until it is repaired.
UNRECOVERABLE - The connection is permanently broken and can no longer be aggregated.
Note: A connection with this status is terminal and cannot be refreshed nor repaired.
DELETED - A connection that is marked deleted is in a final state. This indicates that it will no longer be updated nor actively billed. A customer revoking consent to an existing connection with their bank will cause a connection to be deleted. Deleting a connection can also be triggered from the client-side, i.e. via the delete a connection endpoint. Deleting a customer will also delete all of its connections. A BANK_LINKING_CONNECTION_DELETED webhook will be sent when a connection has been deleted. A deleted connection cannot be recovered; a new connection must be started.
Note: A connection with this status is terminal and cannot be refreshed nor repaired.
UNDETERMINED - Indicates an unforeseen service provider error, or an internal Meld error. Refreshes and reconnects are allowed as the error's true cause is not yet known.
Note: A connection with this status can be both refreshed and repaired as its true status is not yet known.

Connection Errors and Reasons

Status	Status Reason	Description	Can be refreshed?	Can reconnnect?
IN_PROGRESS	null	Customer is in the process of connecting within the widget	No	No
ACTIVE	null	Connection has completed and is healthy. Wait for webhooks to determine when finished aggregating.	Yes	No
EXPIRED	null	Customer has abandoned the widget or has not completed the connection in the allotted time period (4 hours)	No	No
DELETED	null	Connection was deleted	No	No
PARTIALLY_ACTIVE	INSTITUTION_CURRENTLY_UNAVAILABLE	Temporary institution issues; attempt another refresh later.	Yes	Yes
PARTIALLY_ACTIVE	SERVICE_PROVIDER_CURRENTLY_UNAVAILABLE	Refresh after some time, connection is currently degraded due to the service provider having issues.	Yes	Yes
PARTIALLY_ACTIVE	INSTITUTION_ACTION_REQUIRED	Customer action with institution needed and then refresh is possible.	Yes	Yes
PARTIALLY_ACTIVE	INDIVIDUAL_ACCOUNTS_ERROR	Error with aggregating one or more accounts, but not all.	Yes	Yes
PARTIALLY_ACTIVE	PARTIAL_AGGREGATION_SUCCESS	Aggregation was partially successful, but may have been interrupted and not all data or products are available.	Yes	Yes
RECONNECT_AVAILABLE	NEW_ACCOUNTS_AVAILABLE	New accounts can be added if user reconnects.	Yes	Yes
RECONNECT_AVAILABLE	ACCESS_EXPIRING_SOON	Access will expire eventually. User can reconnect to prevent eventual expiry.	Yes	Yes
RECONNECT_REQUIRED	LOGIN_REQUIRED	Credentials changed or MFA required.	Yes	Yes
RECONNECT_REQUIRED	REPAIRING_INSTITUTION	Institution being repaired. Continue to attempt reconnects.	Yes	Yes
RECONNECT_REQUIRED	INTERACTIVE_REFRESH	Customer required for every refresh.	Yes	Yes
RECONNECT_REQUIRED	OTHER		Yes	Yes
UNRECOVERABLE	CONTINUED_AGGREGATION_FAILURES	Aggregation has failed at least three times and has not succeeded for at least two weeks.	Yes	Yes
UNRECOVERABLE	INSTITUTION_DISABLED	The institution is no longer supported.	Yes	Yes
UNRECOVERABLE	OTHER		Yes	Yes
UNDETERMINED	SUBMIT_SERVICE_PROVIDER_TICKET	Submit a ticket to the provider as Meld cannot resolve the issue.	Yes	Yes
UNDETERMINED	INTERNAL_ERROR	Meld error. Notify Meld and retry.	Yes	Yes
UNDETERMINED	OTHER	Any unmapped provider error.	Yes	Yes

Widget Flow Errors

📘
We recommend capturing the following events to close the widget iframe when an error occurs or your customer does not complete the authentication step.

[meld-connect]error -- Emitted when the widget encounters an error

[meld-connect]cancel -- Emitted when your customer cancels the widget

Post-Completion Connection Errors

Completed bank linking connections may enter an error state under select circumstances. This can occur during routine aggregations or in response to the underlying service provider notifying Meld of problems with the connection. When this occurs, a BANK_LINKING_CUSTOMER_ACTION_REQUIRED or BANK_LINKING_CONNECTION_FAILED webhook will be issued, notifying of next steps to take and the reason the connection is broken. Below is the current list of reasons for connection errors along with the actions necessary to repair them:

AUTHORIZATION_REVOKED -> Connection cannot be repaired, notify customer to return to the application, but use default flow to start a new connection
LOGIN_REQUIRED -> Notify the customer to return to the application and repair the connection using the /connect/repair endpoint
OAUTH_REFUSED -> Typically occurs with Finicity connections. Indicates that an account is not capable of being aggregated due to it not being consented on OAuth. File a support ticket with Finicity or notify Meld of such error
INSTITUTION_LOGIN_REQUIRED -> Same action as LOGIN_REQUIRED, but the customer needs to first log in to their institution directly before returning to the application and repairing the connection
UNFORESEEN -> Unforeseen or unhandled error. Treat as a failure until we determine whether the
connection is repairable
UNSUPPORTED_LANGUAGE -> Notify customer to change their language preferences to English with their institution before repairing the connection

Note that all the aforementioned reasons require either repairing the existing connection or creating a new connection altogether. In either case, the customer must return back to the application to connect to their institution again.