Resolving exceptions

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).

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

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

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:

cURL

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 | Bulk resolve | Bulk dispatch

Bulk resolve

Resolve multiple exceptions with a shared resolution:

cURL

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:

cURL

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

cURL

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

cURL

curl -X GET "https://api.matcher.example.com/v1/exceptions/{exceptionId}/comments" \
 -H "Authorization: Bearer $TOKEN"

API Reference: List comments | Add comment | Delete 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

cURL

curl -X GET "https://api.matcher.example.com/v1/disputes?state=OPEN" \
 -H "Authorization: Bearer $TOKEN"

Retrieve a dispute

cURL

curl -X GET "https://api.matcher.example.com/v1/disputes/{disputeId}" \
 -H "Authorization: Bearer $TOKEN"

API Reference: List disputes | Get dispute | Open dispute | Close dispute

Dispute states: DRAFT → OPEN → PENDING_EVIDENCE → WON or LOST.

Exception resolution workflow

Use this flow to keep reviews consistent and audit-friendly.

Triage

Review the queue by severity and SLA. Start with Critical and High.

Investigate

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).

Resolve

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).

Document

Capture enough detail for someone else to replay your decision later:

What you checked
What you concluded
Links or IDs for supporting evidence

Dispatch if needed

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

Work by severity and SLA

Start with Critical and High items. They carry the highest risk and the tightest deadlines.

Make decisions auditable

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

Fix patterns at the source

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

Treat force matches as exceptions to the rule

If you force-match regularly, your rules or tolerances need attention.

Route work automatically

Use assignment rules to reduce triage time and keep ownership clear.

Write-offs are policy calls

If you write off often, revisit thresholds, context scope, or upstream data quality.

Introduction

Getting started

Configuration

Daily reconciliation

Integrations

Reference

Resolving exceptions

What is an exception?

Exception lifecycle

Status definitions

Exception severity

Severity escalation

Resolution methods

1. Force match

2. Create adjustment

3. Write-off

4. Split transaction

Audit requirements

Required documentation by resolution type

Bulk operations

Bulk assign

Bulk resolve

Bulk dispatch

Exception comments

Add a comment

List comments

Disputes

List disputes

Retrieve a dispute

Exception resolution workflow

Best practices

Next steps

Generating Reports

Exception Routing

Introduction

Getting started

Configuration

Daily reconciliation

Integrations

Reference

​What is an exception?

​Exception lifecycle

​Status definitions

​Exception severity

​Severity escalation

​Resolution methods

​1. Force match

​2. Create adjustment

​3. Write-off

​4. Split transaction

​Audit requirements

​Required documentation by resolution type

​Bulk operations

​Bulk assign

​Bulk resolve

​Bulk dispatch

​Exception comments

​Add a comment

​List comments

​Disputes

​List disputes

​Retrieve a dispute

​Exception resolution workflow

​Best practices

​Next steps

Generating Reports

Exception Routing

What is an exception?

Exception lifecycle

Status definitions

Exception severity

Severity escalation

Resolution methods

1. Force match

2. Create adjustment

3. Write-off

4. Split transaction

Audit requirements

Required documentation by resolution type

Bulk operations

Bulk assign

Bulk resolve

Bulk dispatch

Exception comments

Add a comment

List comments

Disputes

List disputes

Retrieve a dispute

Exception resolution workflow

Best practices

Next steps