Resolving exceptions

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 marks a transaction that needs your review. Common causes include:

No candidate found: No transaction in the other source meets the active rule criteria.
Duplicate rejection: A previous match was rejected and no alternative candidate remains.
Source imbalance: One source contains transactions that are not in the other.

Exception lifecycle

Exceptions move through a simple workflow:

When Matcher can’t reconcile a transaction, it creates an exception in OPEN status.
Assigning the exception moves it from OPEN to ASSIGNED. The API does not expose an unassign operation. You must send a non-empty assignee.
Force match and adjust entry set PENDING_RESOLUTION while the operation is in progress. Success moves the exception to RESOLVED.
Direct resolution moves an OPEN or ASSIGNED exception to RESOLVED.
Dispatch writes a DISPATCH audit event and emits exception.dispatched. It does not change the exception status.

Matcher Exception Lifecycle — The lifecycle of an exception in Matcher

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`	Force match or adjust entry is in progress	System
`RESOLVED`	Closed with an auditable resolution	Analyst, System

State-machine endpoints

The following single-exception endpoints change the lifecycle or record related actions. 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`	Records a dispatch to a target system. Body: `targetSystem` (required; `MANUAL` is the target value that records a dispatch), `queue` (optional). Writes a `DISPATCH` audit event and emits `exception.dispatched` without changing status.
Resolve exception	`POST /v1/exceptions/{exceptionId}/resolve`	Resolves a single exception. Body: `resolution` (required), `reason` (optional). Mirrors bulk-resolve validation for one exception. (`OPEN` or `ASSIGNED` → `RESOLVED`)
Force match	`POST /v1/exceptions/{exceptionId}/force-match`	Marks the exception’s transaction as matched and resolves the exception. Body: `overrideReason` (`POLICY_EXCEPTION`, `OPS_APPROVAL`, `CUSTOMER_DISPUTE`, or `DATA_CORRECTION`) and `notes`. Uses `PENDING_RESOLUTION` while the operation is in progress.
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). Uses `PENDING_RESOLUTION` while the operation is in progress.
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 up to 10,000 IDs of the exceptions that match the current filters (`contextId`, `status`, `severity`, `reason`, …). `total` gives the full count, and `truncated` is `true` when the list stops at the cap. Use it to drive a bulk selection before calling the bulk endpoints. (read-only)

MANUAL dispatch acknowledges the hand-off locally without calling an external system.

API Reference:

Assign example

cURL

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

cURL

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

cURL

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": "AMOUNT_CORRECTION",
   "notes": "Correcting processing fee discrepancy"
 }'

Bulk selection with `selectExceptionIDs`

cURL

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

Exception severity

Matcher classifies exceptions by severity so you can work the queue in the right order. The amount is the absolute value of the transaction’s base amount, or of its amount when it has no base amount. For an aged open item, it is the absolute value of the open balance.

Severity	Criteria
Critical	Amount >= 100,000 OR age >= 120 hours
High	Amount >= 10,000 OR age >= 72 hours
Medium	Amount >= 1,000 OR age >= 24 hours
Low	All others

Matcher caps an exception with reason FEE_DATA_MISSING at Medium, whatever its amount or age. These thresholds reprioritize the exception. They do not create an SLA deadline. An inbound callback can supply dueAt, and dashboard aggregates measure compliance for those externally supplied deadlines. Define the response-time policy in the external system that sends the callback.

Severity escalation

Each time a COMMIT matching run finds a transaction still unmatched, Matcher recalculates the severity of the transaction’s unresolved exception, unless it is a duplicate-transaction exception. Age counts from the transaction date or, for an aged open item, from its obligation business date or first-seen time. The classification uses OR logic. Either the amount or the age threshold is enough to trigger a higher severity. A recalculated exception escalates as follows:

An exception under 1,000 starts as Low, but escalates to Medium after 24 hours.

Resolution methods

Matcher exposes three exception-resolution actions.

1. Resolve directly

Close an exception with a required resolution and an optional reason when no force match or adjustment is needed.

2. Force match

Mark the exception’s transaction as matched and resolve the exception. Force match adds the transaction to no match group and pairs it with no counterpart. To pair two transactions, create a manual match with POST /v1/matching/manual. Use Force Match when:

You can clearly explain and document the rationale.
The variance is expected (fees, timing, rounding).

3. Create adjustment

Create an adjusting entry to account for a variance or to balance an unmatched item. Adjustment reason codes:

Reason code	Use case
`AMOUNT_CORRECTION`	Correct the transaction amount
`CURRENCY_CORRECTION`	Correct the transaction currency
`DATE_CORRECTION`	Correct the effective date
`OTHER`	Record another documented correction

Validation rules:

Adjustment amounts must be positive. A request with a zero or negative amount returns a 400 Bad Request error.
POST /v1/exceptions/{exceptionId}/adjust-entry requires a valid ISO 4217 currency code.
reasonCode must use AMOUNT_CORRECTION, CURRENCY_CORRECTION, DATE_CORRECTION, or OTHER.

Resolution records

Matcher records supported resolution actions in the exception history and audit stream.

Resolution	Request fields
Direct resolution	`resolution` (required), `reason` (optional)
Force match	`overrideReason`, `notes`
Adjust entry	`reasonCode`, `amount`, `currency`, `effectiveAt`, `notes`

Matcher does not expose exception split or independent write-off resolution contracts, and it does not enforce amount-based approval thresholds for these actions. Apply any additional approval requirements through your organization’s controls.

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 '{
   "exceptionIds": ["019c96a0-2a10-7dfe-b5c1-8a1b2c3d4e5f", "019c96a0-2b20-7123-9a1b-2c3d4e5f6a7b"],
   "assignee": "john.doe@company.com"
 }'

API Reference:

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 '{
   "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:

cURL

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": "MANUAL",
   "queue": "RECON-TEAM"
 }'

Exception comments

Comments give each exception an audit trail of investigation notes and team discussion. Add a comment as an analyst works an item:

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."
 }'

Listing (GET) returns the full thread ordered oldest-first. You cannot add comments after an exception is resolved. Only the comment author can delete it, and the comment must belong to the exception identified in the URL.

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:

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:

Dispute states and transitions

A new dispute is OPEN. Closing it sets WON or LOST, and both outcomes are terminal.

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 to see why matching failed.
Call GET /v1/matching/candidates with the reconciliation context’s contextId and the exception’s transactionId to review near matches below threshold.
Look for patterns (same counterparty, recurring reference formats).

Resolve

Pick the resolution that best reflects reality and policy.

Resolve directly: You can close the exception without a force match or adjustment.
Force Match: You accept the transaction as matched without a counterpart.
Adjust: You need an adjusting entry for variance.

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. Dispatch records the action but does not change the exception status.

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.

Assign work explicitly

Assign exceptions through the assignment endpoints. Matcher does not apply assignment rules automatically.

Overview

Guides

Console

MCP Server

Operations

Resolving exceptions

What is an exception?

Exception lifecycle

Status definitions

State-machine endpoints

Assign example

Resolve example

Adjust entry example

Bulk selection with `selectExceptionIDs`

Exception severity

Severity escalation

Resolution methods

1. Resolve directly

2. Force match

3. Create adjustment

Resolution records

Bulk operations

Bulk assign

Bulk resolve

Bulk dispatch

Exception comments

Disputes

Dispute states and transitions

Exception resolution workflow

Best practices

Next steps

Generating Reports

Exception Routing

​What is an exception?

​Exception lifecycle

​Status definitions

​State-machine endpoints

​Assign example

​Resolve example

​Adjust entry example

​Bulk selection with selectExceptionIDs

​Exception severity

​Severity escalation

​Resolution methods

​1. Resolve directly

​2. Force match

​3. Create adjustment

​Resolution records

​Bulk operations

​Bulk assign

​Bulk resolve

​Bulk dispatch

​Exception comments

​Disputes

​Dispute states and transitions

​Exception resolution workflow

​Best practices

​Next steps

Generating Reports

Exception Routing

What is an exception?

Exception lifecycle

Status definitions

State-machine endpoints

Assign example

Resolve example

Adjust entry example

Bulk selection with `selectExceptionIDs`

Exception severity

Severity escalation

Resolution methods

1. Resolve directly

2. Force match

3. Create adjustment

Resolution records

Bulk operations

Bulk assign

Bulk resolve

Bulk dispatch

Exception comments

Disputes

Dispute states and transitions

Exception resolution workflow

Best practices

Next steps