> ## Documentation Index
> Fetch the complete documentation index at: https://docs.meld.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Connection Errors and Reasons
Each connection status has an associated `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](/docs/bank-linking/get-connection-data/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](/docs/bank-linking/get-connection-data/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.