statusReason that provides additional insight into why the connection is in that status and what action, if any, you should take. This page is for developers writing lifecycle handlers — use the recommended action column to decide whether to surface a reconnect prompt, schedule a retry, or treat the connection as terminal.
For the high-level status definitions, see Connection Statuses and Errors.
Status and reason reference
| Status | Status Reason | Description | Can be refreshed? | Can reconnect? | Recommended developer action |
|---|---|---|---|---|---|
IN_PROGRESS | null | Customer is in the process of connecting within the widget. | No | No | Wait for the widget flow to finish; do not call refresh or repair. |
EXPIRED | null | Customer abandoned the widget or did not complete the connection in 4 hours. | No | No | Terminal. Create a new connection if the customer returns. |
ACTIVE | null | Connection completed and is healthy. Wait for webhooks to know when aggregation finishes. | Yes | No | Normal operation. Listen for BANK_LINKING_ACCOUNTS_UPDATED and BANK_LINKING_TRANSACTIONS_AGGREGATED. |
ACTIVE | ACCESS_EXPIRING_SOON | Access will expire eventually. Customer can reconnect to prevent expiry. | Yes | Yes | Prompt the customer to reconnect in your UI; call the repair endpoint to generate a connect token. |
ACTIVE | NEW_ACCOUNTS_AVAILABLE | New accounts can be added if the customer reconnects. | Yes | Yes | Optionally surface a “link new accounts” prompt and call the repair endpoint. |
PARTIALLY_ACTIVE | PARTIAL_AGGREGATION_SUCCESS | Aggregation was partially successful; some data or products are missing. | Yes | Yes | Refresh to try again; if it persists, repair the connection. |
PARTIALLY_ACTIVE | INACTIVE_DUPLICATE | The connection is a duplicate of another connection through the same service provider. See Duplicate Connections. | Yes | Yes | Decide whether to keep this duplicate. Delete it if unused; otherwise refresh to promote it to ACTIVE. |
DEGRADED | INSTITUTION_CURRENTLY_UNAVAILABLE | Temporary institution issues. | Yes | Yes | Retry later with exponential backoff; do not prompt the customer immediately. |
DEGRADED | INSTITUTION_ACTION_REQUIRED | Customer action with their institution is required before a refresh can succeed (e.g., re-authorize access in the bank’s app). | Yes | Yes | Forward the message from the BANK_LINKING_CONNECTION_STATUS_CHANGE webhook to the customer; then refresh. |
DEGRADED | SERVICE_PROVIDER_CURRENTLY_UNAVAILABLE | Service provider is experiencing issues. | Yes | Yes | Retry later. If persistent, contact Meld support. |
DEGRADED | INTERACTIVE_REFRESH | Customer participation is required for every refresh on this provider/institution. | Yes | Yes | Avoid scheduled refreshes; only refresh in response to a customer action that returns them to your UI. |
RECONNECT_REQUIRED | LOGIN_REQUIRED | Credentials changed or MFA is required. | Yes | Yes | Send the customer through the repair flow. |
RECONNECT_REQUIRED | REPAIRING_INSTITUTION | Institution is being repaired on the provider’s side. | Yes | Yes | Continue to attempt reconnects periodically until the institution is back. |
RECONNECT_REQUIRED | TOKEN_EXPIRED | Service provider’s connection with the institution expired and needs re-authentication. | Yes | Yes | Send the customer through the repair flow. |
RECONNECT_REQUIRED | OTHER | Various other reasons requiring reconnection. | Yes | Yes | Inspect serviceProviderDetails for specifics; send the customer through the repair flow. |
UNRECOVERABLE | CONTINUED_AGGREGATION_FAILURES | Aggregation has failed at least three times and has not succeeded for at least two weeks. | No | Yes | Treat as broken. Optionally invite the customer to start a fresh connection. |
UNRECOVERABLE | INSTITUTION_DISABLED | The institution is no longer supported by the provider. | No | Yes | Direct the customer to connect a different institution or via a different provider via routing. |
UNRECOVERABLE | OTHER | Various other reasons that have made the connection unrecoverable. | No | Yes | Inspect serviceProviderDetails; consider creating a new connection. |
UNDETERMINED | AGGREGATION_TIMEOUT | A timeout prevented the service provider aggregation from completing. | Yes | Yes | Retry the refresh after a short delay. |
UNDETERMINED | SUBMIT_SERVICE_PROVIDER_TICKET | Submit a ticket to the provider; Meld cannot resolve. | Yes | Yes | Open a ticket with the underlying service provider; retry the refresh after they confirm a fix. |
UNDETERMINED | UNKNOWN_SERVICE_PROVIDER_ERROR_CODE | A provider error code Meld has not seen before. | Yes | Yes | Notify Meld support with the connectionId and the raw provider error; retry the refresh. |
UNDETERMINED | INTERNAL_ERROR | Meld internal error. | Yes | Yes | Notify Meld support; retry the refresh. |
DELETED | null | Connection was deleted. | No | No | Terminal. Start a new connection if the customer wants to reconnect. |
The
BANK_LINKING_CONNECTION_STATUS_CHANGE webhook fires whenever a connection moves between statuses or status reasons. Always use this webhook as the source of truth — do not poll the connections endpoint on a schedule.