> ## Documentation Index
> Fetch the complete documentation index at: https://docs.case.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Errors & Recovery
> What each failure means and which ones to retry
Connector failures fall into two groups: **request errors**, returned immediately from the call you made, and **provider failures**, which happen mid-run and are reported per file.
Raw provider error messages and response bodies are never persisted or returned. What you receive is a fixed set of codes. This keeps another system's internal detail—file names, user identities, tenant structure—out of your logs and your users' screens.
***
## Request errors
These come back from the call you just made.
| Code | Status | Cause | Fix |
| ----------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
| `connector_scope_not_enabled` | 403 | The provider or scope tier is not enabled for your organization | Contact support to have it enabled |
| `provider_scope_insufficient` | 403 | The connection's consent is too narrow to browse server-side. Rare; typically an older connection authorized at a reduced tier. | Reconnect |
| `installation_required` | 403 | Your organization hosts an application and `X-Case-Installation-Id` was missing | Send the header—there is no fallback |
| `installation_invalid` | 403 | Unknown installation, or one belonging to another organization | Check the id you cached |
| `installation_disabled` | 403 | The installation is not `active` | Re-enable it before retrying |
| `connector_subject_invalid` | 400 | `X-Case-Connector-Subject` does not match `^[A-Za-z0-9_-]{1,255}$` | Fix the value you derive server-side |
A `connect_url` that has expired returns `410`; one that has already been used returns `404`. Either way, generate a fresh one.
## Provider failures
Every provider error is classified before it touches your data. The classification decides whether the run retries, fails the file, or stops.
| Code | Class | Retried? | What it means |
| ----------------------------------- | ------------ | ----------------- | ---------------------------------------------------------- |
| `provider_reauthorization_required` | reauth | No | Authorization lapsed beyond refresh |
| `provider_access_lost` | access\_lost | No | The linked folder is no longer reachable with this account |
| `provider_item_not_found` | not\_found | No | The item is gone |
| `provider_rate_limited` | throttled | Yes, with backoff | The provider is throttling |
| `provider_temporarily_unavailable` | transient | Yes | Provider-side outage or 5xx |
| `provider_operation_rejected` | permanent | No | The provider refused the operation |
Two more are specific rather than classified:
| Code | Meaning | Fix |
| ------------------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------ |
| `connector_selection_too_large` | The selected folder exceeds the safe scan bounds—too many items, too deep, or too large to checkpoint | Import a smaller folder |
| `connector_file_too_large` | A file turned out larger than `filters.max_size_bytes` once its bytes were read | Raise the limit, or exclude the file |
## Recovering from each
### Reauthorization required
The most common one. Refresh tokens get revoked when a user changes their password, an admin removes an app, or a provider expires a grant.
The connection moves to `reauth_required` and a [`connection.reauth_required`](/events/event-types) event fires. Links stop; nothing is lost.
Send the user through the [connect flow](/connectors/oauth#reconnecting) again. Because reconnection merges into the existing connection, links resume with their ledgers and cursors intact and nothing re-imports.
### Access lost
The account still works, but the linked folder does not. Someone moved it, deleted it, or removed this user's access.
The link becomes `orphaned` with an `orphan_reason`:
| Reason | Meaning |
| ---------------------- | -------------------------------------------------- |
| `provider_folder_gone` | The folder no longer exists |
| `provider_access_lost` | It exists, but this account can no longer reach it |
| `vault_deleted` | The destination vault was deleted |
An orphaned link will not run again. Point the user at a new folder with a fresh transfer, or delete the link.
### Throttling
Backoff is automatic. The run slows down and keeps going; you do not need to do anything.
For interactive browse calls, a `429` may carry `Retry-After` when a retry deadline is known—honor it rather than looping.
Interactive browsing and background runs share one request budget per provider account. A large sync in progress can make browsing feel slow for the same user. This is most noticeable on providers with tight rate limits—see the [provider guides](/connectors/providers).
### Transient failures
Retried automatically within the run. If a run ends `completed_with_errors`, the files that failed are in the ledger with `state=failed`. Re-post the same transfer to retry only those—the ledger means settled files are not touched again.
### Permanent failures
The file failed and will not be retried. Read the row from `GET /connectors/v1/links/{id}/objects?state=failed` and surface it to the user.
## What a crash does not do
Transfers are built so that an interrupted run is safe to resume:
* Every external side effect is preceded by a persisted ledger intent, so a retry lands on the same identity instead of creating a duplicate
* Files stream end to end and nothing buffers whole, so a large file cannot exhaust memory mid-run
* Deleting a link soft-deletes it before cancelling its run, so an in-flight executor cannot resurrect it
You do not need to build deduplication on top of this. Re-posting a transfer is always safe.
## A practical error-handling loop
1. On `run.failed`, read `error` from the run and decide whether it is reauth, access loss, or something else
2. On `run.completed` with `status: "completed_with_errors"`, pull `?state=failed` from the ledger and show the affected files
3. On `connection.reauth_required`, prompt the user to reconnect—do not delete anything
4. On `link.orphaned`, ask the user to reselect a folder
5. Treat `403 installation_required` as a bug in your request path, not a permissions problem
## Next steps
Run mechanics, ledger states, and progress
Full payloads for connector lifecycle events
Rate budgets and capability differences per provider