# Reconnect Flow
URL: https://www.quiltt.dev/connector/reconnect
Description: Learn how to repair Connections that enter into a user-repairable error state.
Navigation: connector → reconnect
Tags: Connector
Content Length: 7k characters

Connections can sometimes enter into an error state that prevents new data from being synced. While some errors are intermittent in nature due to upstream connectivity issues with the institution, Connections can also break due to a simple password change or security upgrade at the bank. When Quiltt detects that a Connection that can be repaired by user interaction with the Connector, the following will occur:

1. The Connection `status` will change to `ERROR_REPAIRABLE`, firing the `connection.synced.errored.repairable` webhook event.
2. Regular syncing will be interrupted and no new data will be synced, including associated accounts and transactions, until the Connection is repaired.
3. Account Balance Refreshes and other per-Connection actions in the REST API will start returning `403 Forbidden`.
4. To restore syncing, the user will need to complete the **Reconnect** Flow by re-authenticating with their financial institution.

## Why Connections break and how often to expect it

A Connection entering an error state is a normal part of its lifecycle, not a one-off failure. A Connection that synced cleanly can move into `ERROR_REPAIRABLE` days later with no change on your side — most often because the user changed their password, the institution required new multi-factor authentication, or the provider's stored consent or session expired.

How often this happens depends on the institution and the provider serving the Connection:

- **OAuth connections at large institutions** (for example, a Chase connection over OAuth) can stay healthy for up to a year before they need re-authentication.
- **Screen-scraped connections at smaller institutions** can break far more often — sometimes every few days — because they depend on credentials and security prompts that change frequently.

Because breakage is expected, design for reconnection as an ongoing part of your integration rather than an exception:

1. Subscribe to the `connection.synced.errored.repairable` webhook, or watch the `Connection.status` field, so you learn as soon as a Connection needs repair.
2. Surface a clear prompt to the affected user and route them into the [Reconnect flow](#implementing-reconnect).
3. Treat repeated re-authentication for a given institution as routine. If one institution fails unusually often on its current provider, contact Quiltt Support with the Connection ID — some institutions sync more reliably through a different provider.

Info:
To find out why a specific Connection broke, inspect its [Remote Data](/api/remote-data) in the Dashboard. The provider attaches its own error code and message — for example, a Finicity `185` code indicates a multi-factor authentication issue. See [Troubleshooting Connection Errors](/api/connections#troubleshooting-connection-errors) for how to interpret provider error codes.

## Implementing Reconnect

To allow your end-user to repair the Connection, simply pass the Connection ID to the Connector SDK. See the examples below and the relevant [SDK docs](/connector/sdk) for platform-specific instructions.

Upon launching the Connector, your user will be automatically prompted to re-authenticate to their institution using the current upstream provider (i.e. MX, Finicity or Plaid). Once they have successfully re-authenticated, the Connection will resume syncing. You can track the Connection status via webhooks, GraphQL subscription or via polling.

### Examples

Code Examples:

  ```html
    [" quiltt-connection="<CONNECTION_ID>">
      Reconnect]
    ```
  ```tsx
    import {QuilttButton} from '@quiltt/react'

    export const App = () => {
      return (
        

QuilttButton:
"
          connectionId="<CONNECTION_ID>"
          // See the JavaScript API for the full list of available callbacks
          onExitSuccess={(metadata) => [console.log('Reconnected: ', metadata.connectionId)]}
        >
          Reconnect

      )
    }
    ```
  ```tsx
    import {QuilttConnector} from '@quiltt/react-native'

    export const ConnectorScreen = ({navigation}) => {
      return (
        <QuilttConnector
          connectorId="<CONNECTOR_ID>"
          connectionId="<CONNECTION_ID>"
          appLauncherUrl="<YOUR_HTTPS_APP_LINK>"
          // See the JavaScript API for the full list of available callbacks
          onExitSuccess={(metadata) => [console.log('Connected ' + metadata.connectionId)]}
        />
      )
    }
    ```

### Client-side Connector Events

When the user successfully completes the flow, the Connector `exited.successful` event will fire. You can attach a callback with the JavaScript API or use the `onExitSuccess` prop on the React component. The `connectionId` will be passed to the callback as metadata, alongside the `connectorId` and `profileId`.

See the [JavaScript API guide](/connector/javascript) for more information about the event.

### Server-side Webhooks

To have your server be notified when a Connection needs to be repaired, you can subscribe to the `connection.synced.errored.repairable` event via [Webhooks](/webhooks).

When the Connection successfully syncs, a `connection.synced.successful` event will fire, and the Connection status will change to `SYNCED`.

### GraphQL Subscriptions

You can also subscribe to real-time updates on the Connection status with the [`connectionSynced`](/api/graphql/subscriptions) GraphQL Subscription. This approach can be used client-side or server-side.

## How to Simulate a Connection Error

To test the flow, you can place `SANDBOX` Connections into a user-repairable state using the [`connectionSimulateError` GraphQL mutation](/api-reference/graphql#mutation-connectionSimulateError).

You can call the mutation in the GraphQL Explorer from [the Quiltt Dashboard](https://dashboard.quiltt.dev), or by calling the Profile GraphQL API.

You can simulate an error in the [Quiltt Hub demo](https://demo.quiltthub.com) to see what the experience is like for the user.

Info:
Note that today in `DEMO` and `SANDBOX` environments only, Finicity Connections will enter into `DISCONNECTED` status and not `ERROR_REPAIRABLE`.

These Connections can still be passed to the [Connector Reconnect Flow](/connector/reconnect) to be reconnected by the end-user.

#### Request

```graphql
mutation SimulateError {
  connectionSimulateError(input: [id: "conn_14TJiFDKRJlPiBHuukUIlXZ"]) {
    success
    record [id
      status]
  }
}
```

#### Response

```json
{
  "data": {
    "success": true,
    "record": ["id": "conn_14TJiFDKRJlPiBHuukUIlXZ",
      "status": "ERROR_REPAIRABLE"]
  }
}
```

## Reconnecting `DISCONNECTED` Connections

In addition to repairing connections that enter an `ERROR_REPAIRABLE` state, you can use **Reconnect** to "revive" connections that were previously put in a `DISCONNECTED` state. This can be used to support migrating connections between different providers.

With a `DISCONNECTED` Connection, the end-user will be prompted to authenticate into the Connection's institution using the best-suited provider provisioned on the Connector. Once the user has successfully authenticated, Quiltt will create a new Connection, and any relevant data from the `DISCONNECTED` Connection will be transferred to the new Connection.

Since a new Connection ID will be generated, you will want to listen to the `onExitSuccess` callback to capture the new ID and, if your implementation requires it, register it with your backend.