> ## 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`.
### 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 |
## 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 '{
"exception_ids": ["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 '{
"exception_ids": ["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 '{
"exception_ids": ["019c96a0-2a10-7dfe-b5c1-8a1b2c3d4e5f"],
"target_system": "JIRA",
"queue": "RECON-TEAM"
}'
```
## Exception comments
***
Comments provide an audit trail of team discussions and investigation notes on exceptions.
### Add a comment
```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."
}'
```
### List comments
```bash cURL theme={null}
curl -X GET "https://api.matcher.example.com/v1/exceptions/{exceptionId}/comments" \
-H "Authorization: Bearer $TOKEN"
```
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 requires formal investigation or involves an external party, escalate it to a dispute. Disputes track evidence, state changes, and resolution outcomes.
### List disputes
```bash cURL theme={null}
curl -X GET "https://api.matcher.example.com/v1/disputes?state=OPEN" \
-H "Authorization: Bearer $TOKEN"
```
### Retrieve a dispute
```bash cURL theme={null}
curl -X GET "https://api.matcher.example.com/v1/disputes/{disputeId}" \
-H "Authorization: Bearer $TOKEN"
```
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: `DRAFT` → `OPEN` → `PENDING_EVIDENCE` → `WON` or `LOST`.
## 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.