Start here when a connected account stops working

A connected account can become temporarily unavailable after it was linked successfully. You might observe one or more of these symptoms:

An account or product is no longer running.
An API Method that previously worked now returns an error.
Provider-derived realtime events stop arriving.
A workflow that depends on a connected account can no longer continue.

These symptoms do not necessarily mean that the Unipile API is down. Unipile operates between your application and a third-party provider, and the provider connection required for an operation has its own availability state.

📘
Before going further, read Building on third-party providers. It explains why provider interruptions are expected, what Unipile maintains, and what your application must handle.

⚠️
Required integration behavior
Error handling must be more comprehensive than for an API that controls every underlying operation. Temporary provider failures must be handled by your application. Unipile provides normalized connection statuses, account lifecycle webhooks, errors, retries, and reconnection flows to make that handling as simple and consistent as possible across providers. Providing these tools is Unipile's responsibility; implementing them is the application operator's responsibility. If an application does not implement them and breaks when provider connectivity changes, Unipile cannot be held responsible for the resulting downstream failure.

1. Check the account and product status

Retrieve the Account object or inspect it in the Dashboard. For multi-product accounts, check both the top-level status and each value in metadata.products_connection_status.

Status	Meaning	What your application should do
`running`	The connection is currently operational.	Inspect the API error or webhook delivery separately.
`disconnected`	Authentication or configuration is required.	Tell the account owner and provide a reconnection action.
`errored`	A service interruption affects Unipile, the provider, or a proxy.	Keep the workflow paused and wait for recovery; do not ask the user to reconnect unless instructed.
`partial`	At least one product works and another requires authentication.	Keep operational products available and reconnect the affected product.
`degraded`	At least one product works and another has a service interruption.	Keep operational products available and wait for the affected product to recover.

See Connection Status for the complete lifecycle, product-level behavior, webhook payloads, and reconnection instructions.

2. Identify the affected layer

The Unipile API cannot be reached

If requests do not reach Unipile or the platform returns an internal API error, the problem is on the Unipile API path. Retry only when appropriate for the operation and use the request ID when contacting support.

Unipile responds with a provider or proxy error

The Unipile API is reachable, but the dependency needed to complete the operation is unavailable or rejected the request. Use the error type to distinguish provider, proxy, authorization, rate-limit, and validation failures. See Error responses.

The account requires authentication

A disconnected status or provider/invalid_authorization response means the provider session or credentials can no longer authorize the connection. Prompt the account owner to reconnect the existing account.

The account has a service interruption

An errored status means the connection is interrupted because of Unipile, the provider, or a proxy. Unipile automatically retries recoverable failures and works to adapt the connector when a provider change is involved. The user usually cannot resolve this state by authenticating again.

3. Diagnose the symptom

An API Method stopped working

Check the account and affected product status.
Inspect the HTTP status, error type, detail, and req_id.
Retry only if the operation is safe to repeat and the error is temporary.
Pause dependent workflows while the required product is unavailable.
If the account is still running, check provider limits, permissions, feature availability, and the method-specific documentation.

A provider can change a specific endpoint or behavior without breaking every capability. An account may therefore remain running while one Method is temporarily affected.

Provider-derived realtime events stopped

Check the status of the account and affected product.
Check the webhook logs to confirm whether Unipile created and delivered the events.
Verify that your webhook endpoint is reachable and accepts the configured events.
If provider connectivity was interrupted, keep your synchronization workflow paused and reconcile provider data after recovery when consistency matters.

Account status events are designed to notify your application about connection transitions. Provider-derived events cannot be received or forwarded while Unipile cannot access the provider.

The account repeatedly disconnects

Check whether the account owner changed credentials, revoked the session, logged out, or must complete a provider checkpoint. Also review provider limits, account activity, authentication method, and proxy configuration. Repeated disconnects can result from provider security or anti-abuse behavior rather than an Unipile API outage.

4. Build the recovery experience

Your application must treat provider connectivity as a dynamic state. The following behaviors are part of a production-ready integration:

Subscribe to account.status.* webhooks.
Store the latest account and product statuses.
Prevent a provider failure from breaking unrelated features or accounts.
Display whether the user must reconnect or simply wait for recovery.
Pause and safely resume dependent jobs.
Handle API errors even when the last known account status was running.
Reconcile data after an interruption when missing events would matter.

A successful connection is a point-in-time state, not a guarantee of future provider availability. Unipile centralizes connector maintenance and exposes the status, webhook, and error primitives your application needs to recover gracefully.

Contacting support

If the documented recovery action does not resolve the issue, include the following information when contacting Unipile support:

Account ID and affected product.
Approximate start time and timezone.
API Method and request parameters with secrets removed.
HTTP status, error type, detail, and req_id.
Relevant webhook conversation or event IDs.
Whether the issue affects one account, one provider, or all accounts.

This information helps distinguish an account-specific problem from a provider change, proxy failure, or Unipile incident.