> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.
# Resolving exceptions
> Review, prioritize, and resolve transactions Matcher couldn't reconcile automatically using severity, lifecycle, and audit-friendly actions.
Exceptions are transactions that Matcher can't reconcile automatically. This guide shows how to review exceptions, prioritize work based on severity, and resolve items with the right level of documentation.
## What is an exception?
***
An exception is created when a transaction from one source has no valid counterpart in another source. Common causes include:
* **No candidate found**: No transaction in the other source meets the active rule criteria.
* **Below confidence threshold**: Candidates exist, but score below the minimum confidence (default: 60).
* **Duplicate rejection**: A previous match was rejected and no alternative candidate remains.
* **Source imbalance**: One source contains transactions that are missing from the other.
## Exception lifecycle
***
Exceptions move through a simple workflow:
* When Matcher can't reconcile a transaction, it creates an exception in `OPEN` status.
* From there, the exception is assigned to an analyst for investigation (`ASSIGNED`).
* If the resolution depends on an external system — such as a dispatched JIRA issue or webhook callback — the exception moves to `PENDING_RESOLUTION` until the external response arrives.
* Once the analyst resolves the exception (force match, adjustment, or external callback), it transitions to `RESOLVED`. Resolution isn't gated on dispatch — an exception can move to `RESOLVED` from `OPEN`, `ASSIGNED`, or `PENDING_RESOLUTION`.
### Status definitions
| Status | Description | Who Can Transition |
| -------------------- | --------------------------------------------------- | ------------------ |
| `OPEN` | New exception waiting for assignment | System |
| `ASSIGNED` | Assigned to an analyst for investigation | System, Analyst |
| `PENDING_RESOLUTION` | Awaiting external response (JIRA, webhook callback) | System |
| `RESOLVED` | Closed with an auditable resolution | Analyst, System |
### State-machine endpoints
The following single-exception endpoints drive the transitions in the lifecycle above. Each is addressed by the exception's `exceptionId` in the path.
| Endpoint | Method & path | Purpose | | |
| -------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- | ---------------------------------- |
| Assign exception | `POST /v1/exceptions/{exceptionId}/assign` | Assigns the exception to an analyst. Body: `assignee` (required). Returns the updated exception. (`OPEN` → `ASSIGNED`) | | |
| Dispatch exception | `POST /v1/exceptions/{exceptionId}/dispatch` | Dispatches the exception to an external ticketing system (e.g. JIRA, ServiceNow). Body: `DispatchRequest`. Returns a `DispatchResponse`. (`ASSIGNED` → `PENDING_RESOLUTION`) | | |
| Resolve exception | `POST /v1/exceptions/{exceptionId}/resolve` | Resolves a single exception. Body: `resolution` (required), `reason` (optional). Mirrors bulk-resolve validation for one exception. (`OPEN` | `ASSIGNED` | `PENDING_RESOLUTION` → `RESOLVED`) |
| Adjust entry | `POST /v1/exceptions/{exceptionId}/adjust-entry` | Resolves an exception by creating an accounting adjustment entry. Body: `amount`, `currency`, `effectiveAt`, `notes`, `reasonCode` (all required). (resolves via adjustment) | | |
| Exception history | `GET /v1/exceptions/{exceptionId}/history` | Returns the ordered history of state transitions and actions for the exception (`HistoryResponse`). Supports `cursor`/`limit` pagination. *(read-only)* | | |
| Select exception IDs | `GET /v1/exceptions/ids` | Returns the full set of exception IDs matching the current filters (`contextId`, `status`, `severity`, `reason`, …). Use it to drive a bulk selection before calling the bulk endpoints. *(read-only)* | | |
API Reference:
* [Assign exception](/en/reference/matcher/assign-exception)
* [Dispatch exception](/en/reference/matcher/dispatch-exception)
* [Resolve exception](/en/reference/matcher/resolve-exception)
* [Adjust entry](/en/reference/matcher/adjust-entry-exception)
* [Get exception history](/en/reference/matcher/retrieve-exception-history)
* [Select exception IDs](/en/reference/matcher/select-exception-ids)
#### Assign example
```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/exceptions/{exceptionId}/assign" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{ "assignee": "john.doe@company.com" }'
```
#### Resolve example
```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/exceptions/{exceptionId}/resolve" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{ "resolution": "ACCEPTED", "reason": "Variance within tolerance" }'
```
#### Adjust entry example
```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/exceptions/{exceptionId}/adjust-entry" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"amount": "150.50",
"currency": "BRL",
"effectiveAt": "2026-02-02T16:40:00Z",
"reasonCode": "FEE_ADJUSTMENT",
"notes": "Correcting processing fee discrepancy"
}'
```
#### Bulk selection with `selectExceptionIDs`
```bash cURL theme={null}
curl -X GET "https://api.matcher.example.com/v1/exceptions/ids?contextId={contextId}&status=OPEN&severity=CRITICAL" \
-H "Authorization: Bearer $TOKEN"
```
Feed the returned IDs into the [bulk operations](#bulk-operations) below.
## Exception severity
***
Matcher classifies exceptions by severity so you can work the queue in the right order.
| Severity | Criteria | SLA |
| ------------ | ------------------------------------- | ------------------ |
| **Critical** | Amount >= 100,000 OR age >= 120 hours | 24 hours |
| **High** | Amount >= 10,000 OR age >= 72 hours | 72 hours |
| **Medium** | Amount >= 1,000 OR age >= 24 hours | 120 hours (5 days) |
| **Low** | All others | 168 hours (7 days) |
### Severity escalation
Severity is re-evaluated as an exception ages. The classification uses OR logic — either the amount or the age threshold is enough to trigger a higher severity:
* An exception under 1,000 starts as **Low**, but escalates to **Medium** after 24 hours.
* An exception under 10,000 escalates to **High** after 72 hours.
* Any unresolved exception escalates to **Critical** after 120 hours.
## Resolution methods
***
You can resolve an exception in four ways.
### 1. Force match
Manually link transactions when you've confirmed they belong together, but the system couldn't match them.
**Use Force Match when:**
* The correct counterpart exists, but variances blocked automatic matching.
* You can clearly explain and document the rationale.
* The variance is expected (fees, timing, rounding).
Force Match bypasses scoring and rule logic. Use it only when you can justify the decision in writing.
### 2. Create adjustment
Create an adjusting entry to account for a variance or to balance an unmatched item.
**Common adjustment types:**
| Type | Use Case |
| ------------------- | --------------------------------------- |
| `BANK_FEE` | Bank charges not recorded in the ledger |
| `FX_VARIANCE` | Currency conversion differences |
| `TIMING_DIFFERENCE` | Settlement timing adjustments |
| `ROUNDING` | Small rounding differences |
| `CORRECTION` | Error corrections |
| `OTHER` | Other documented variances |
**Validation rules:**
* Adjustment amounts must be positive. A request with a zero or negative amount returns a `400 Bad Request` error.
* Currency codes must follow ISO 4217 format.
* Reason codes must use a valid predefined value: `AMOUNT_CORRECTION`, `CURRENCY_CORRECTION`, `DATE_CORRECTION`, or `OTHER`.
### 3. Write-off
Write off a transaction that has no valid counterpart. This should be rare and typically requires approval.
**Write-off reasons:**
| Reason | Description |
| ------------------- | ------------------------------------------- |
| `DUPLICATE_ENTRY` | Transaction was entered twice |
| `CANCELLED` | Transaction was reversed or cancelled |
| `NOT_APPLICABLE` | Doesn't belong in this reconciliation scope |
| `BELOW_THRESHOLD` | Amount is below the investigation threshold |
| `APPROVED_VARIANCE` | Variance approved by management |
Write-offs remove items from your reconciliation outcome. Treat them as a policy decision, not a convenience.
### 4. Split transaction
Use split when one transaction should match multiple counterparts.
## Audit requirements
***
Every resolution creates an audit record. Some resolution types require stronger evidence and approvals.
### Required documentation by resolution type
| Resolution | Required Fields | Approval Needed |
| ----------- | ------------------------------------------ | ------------------------------ |
| Force Match | `reason`, `notes` | No (unless amount > threshold) |
| Adjustment | `adjustment_type`, `amount`, `description` | If amount > \$1,000 |
| Write-Off | `reason`, `notes`, `reference_document` | Always |
| Split | `splits[]` with amounts and targets | No |
## Bulk operations
***
When dealing with large volumes of exceptions, bulk endpoints let you process up to 100 exceptions in a single request.
### Bulk assign
Assign multiple exceptions to a team member at once:
```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/exceptions/bulk/assign" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"exceptionIds": ["019c96a0-2a10-7dfe-b5c1-8a1b2c3d4e5f", "019c96a0-2b20-7123-9a1b-2c3d4e5f6a7b"],
"assignee": "john.doe@company.com"
}'
```
API Reference:
* [Bulk assign](/en/reference/matcher/bulk-assign-exceptions)
* [Bulk resolve](/en/reference/matcher/bulk-resolve-exceptions)
* [Bulk dispatch](/en/reference/matcher/bulk-dispatch-exceptions)
### Bulk resolve
Resolve multiple exceptions with a shared resolution:
```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/exceptions/bulk/resolve" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"exceptionIds": ["019c96a0-2a10-7dfe-b5c1-8a1b2c3d4e5f", "019c96a0-2b20-7123-9a1b-2c3d4e5f6a7b"],
"resolution": "ACCEPTED",
"reason": "Verified as valid bank fees"
}'
```
The response includes `succeeded` and `failed` arrays, so you can handle partial failures gracefully.
### Bulk dispatch
Dispatch multiple exceptions to an external system:
```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/exceptions/bulk/dispatch" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"exceptionIds": ["019c96a0-2a10-7dfe-b5c1-8a1b2c3d4e5f"],
"targetSystem": "JIRA",
"queue": "RECON-TEAM"
}'
```
## Exception comments
***
Comments give each exception an audit trail of investigation notes and team discussion — invaluable when someone else has to pick up or review the case later. Add a comment as an analyst works an item:
```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/exceptions/{exceptionId}/comments" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"content": "Contacted bank to verify wire transfer fee. Awaiting confirmation."
}'
```
Listing (`GET`) returns the full thread ordered oldest-first, and a comment can be removed by its `commentId`.
| Action | Method & path | Key fields |
| -------------- | ---------------------------------------------------------- | ----------------------------------------- |
| Add comment | `POST /v1/exceptions/{exceptionId}/comments` | `content` (comment body) |
| List comments | `GET /v1/exceptions/{exceptionId}/comments` | — (returns the full thread, oldest first) |
| Delete comment | `DELETE /v1/exceptions/{exceptionId}/comments/{commentId}` | `commentId` in path |
API Reference:
* [List comments](/en/reference/matcher/list-exception-comments)
* [Add comment](/en/reference/matcher/add-exception-comment)
* [Delete comment](/en/reference/matcher/delete-exception-comment)
## Disputes
***
When an exception needs formal investigation or involves an external party — a chargeback, a bank query — escalate it to a **dispute**. Disputes track evidence, state changes, and the final outcome. List disputes with `GET /v1/disputes` (filter by `state`, e.g. `OPEN`) or retrieve one by its `disputeId`.
API Reference:
* [List disputes](/en/reference/matcher/list-disputes)
* [Get dispute](/en/reference/matcher/retrieve-dispute)
* [Open dispute](/en/reference/matcher/open-dispute)
* [Close dispute](/en/reference/matcher/close-dispute)
### Dispute states and transitions
A dispute has five states: `DRAFT`, `OPEN`, `PENDING_EVIDENCE`, `WON`, and `LOST`. The flow is **not** strictly linear:
* `PENDING_EVIDENCE` is **optional** — an `OPEN` dispute can go directly to `WON` or `LOST` without ever collecting evidence.
* A `LOST` dispute can be **reopened** back to `OPEN`.
* `WON` is terminal.
The complete set of valid transitions:
| From state | Allowed next states | Notes |
| ------------------ | --------------------------------- | ------------------------------------------------------- |
| `DRAFT` | `OPEN` | Dispute is opened for investigation |
| `OPEN` | `PENDING_EVIDENCE`, `WON`, `LOST` | Can resolve directly, or request evidence first |
| `PENDING_EVIDENCE` | `OPEN`, `WON`, `LOST` | Returns to `OPEN` or resolves once evidence is reviewed |
| `WON` | *(none)* | Terminal state |
| `LOST` | `OPEN` | A lost dispute can be reopened |
## Exception resolution workflow
***
Use this flow to keep reviews consistent and audit-friendly.
Review the queue by severity and SLA. Start with Critical and High.
Use the exception payload to understand what failed and what candidates exist.
* Read `reason_details` to see why matching failed.
* Review `candidates` for near matches below threshold.
* Look for patterns (same counterparty, recurring reference formats).
Pick the resolution that best reflects reality and policy.
* **Force Match**: You found the correct counterpart.
* **Adjust**: You need an adjusting entry for variance.
* **Split**: One transaction maps to multiple counterparts.
* **Write-Off**: No counterpart exists and policy allows it (approval required).
Capture enough detail for someone else to replay your decision later:
* What you checked
* What you concluded
* Links or IDs for supporting evidence
If the exception requires external handling, dispatch it to JIRA or a webhook endpoint. The exception moves to `PENDING_RESOLUTION` until a callback confirms the outcome.
## Best practices
***
Start with Critical and High items. They carry the highest risk and the tightest deadlines.
Notes aren't optional. Treat them as part of the resolution:
* What you checked
* Why this resolution is correct
* Any ticket IDs, statements, or confirmations
Repeating exceptions usually point to configuration issues:
* Same counterparty → Normalize names or mapping
* Same date window → Validate ingestion completeness
* Same source → Review field mapping and sign conventions
If you force-match regularly, your rules or tolerances need attention.
Use assignment rules to reduce triage time and keep ownership clear.
If you write off often, revisit thresholds, context scope, or upstream data quality.
## Next steps
***
Create reconciliation reports, export results, and support audits.
Configure severity rules, SLAs, and automatic assignment.