> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.merge.dev/merge-unified/knowledge-base/linked-account/issues/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.merge.dev/_mcp/server.

# Issues

> What a Merge Issue is, how the ONGOING and RESOLVED statuses change, and how to read issues through the API or react to them through webhooks.

---

Merge opens an Issue when requests to a third party start failing in a way that someone has to act on, most often expired credentials or a permission the end user never granted. One Issue covers one problem on one Linked Account, so repeated failures of the same kind update the existing Issue rather than piling up new ones.

| Status     | When Merge sets it                                                                                                                                                                                                   |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ONGOING`  | The moment Merge classifies the failure                                                                                                                                                                              |
| `RESOLVED` | Once requests to the third party are succeeding again and at least a day has passed since the last failure. A [relink](/merge-unified/merge-link/relinking) resolves every ongoing Issue on the account immediately. |

Because resolution waits out that day, a connection that has just been fixed can still show an ongoing Issue for a while.

`error_description` is a short label for the failure, such as `Invalid login credentials`, `Missing permission`, or `Expired multi-factor authentication`, and `error_details` lists the specific requests or scopes involved. Linked Accounts that Merge syncs from report files instead of an API carry descriptions about the file, such as `Unrecognized file name`.

Most of what a developer needs from Issues arrives without polling. The **Linked Account issues** webhook delivers `Issue.new`, `Issue.reopened`, `Issue.muted`, and `Issue.resolved`, which is enough to keep a connection-health indicator in your own product accurate. Use the endpoints below to backfill state, to reconcile after downtime, or to show the current issue list for one Linked Account with the `linked_account_id` filter.

Mute an Issue you have decided not to act on from the **Issues** page in your dashboard. Muted issues stay out of `GET /issues` unless you pass `include_muted=true`, and muting emits `Issue.muted` with `is_muted` set to `true` in the payload.

> Build once. Connect to every API, tool, and LLM. Ship products and agents to production without owning the integration stack.


## API Docs

- Issues [/issues](https://docs.merge.dev/merge-unified/knowledge-base/linked-account/issues/list.md)
- Issues [/issues/{id}](https://docs.merge.dev/merge-unified/knowledge-base/linked-account/issues/retrieve.md)

## OpenAPI Specification

The raw OpenAPI 3.1 specification for this API is available at:
- [OpenAPI JSON](https://docs.merge.dev/merge-unified/knowledge-base/linked-account/issues/openapi.json)
- [OpenAPI YAML](https://docs.merge.dev/merge-unified/knowledge-base/linked-account/issues/openapi.yaml)