Get exceptions

This recipe shows how to retrieve exceptions from the analyst review queue. Exceptions are transactions where the match engine could not produce a high-confidence match (confidence below the analyst_review_threshold).

Endpoint

GET /v1/exceptions

Returns an array of exceptions with the exception UUID, source transactions, confidence score, reason, severity, and assignment status.

Prerequisites

• A valid tenantId and bearer JWT.
• The user must have at least one of: tenant_admin, tenant_analyst.

Request

curl -X GET "https://api.falconveritas.com/v1/exceptions?limit=50&severity=high&assignedTo=me" \
  -H "Authorization: Bearer $FVI_JWT" \
  -H "X-Tenant-Id: $FVI_TENANT_ID" \
  -H "Content-Type: application/json"

Response

{
  "items": [
    {
      "id": "exc-001",
      "tenant_id": "f1a4e6e2-4b3e-4d2e-9b9c-3a2e9b1f4d5a",
      "left_transaction_id": "txn-12345",
      "right_transaction_id": "txn-67890",
      "confidence_score": 0.62,
      "reason": "amount_mismatch",
      "severity": "high",
      "amount_difference": 50.00,
      "currency": "USD",
      "assigned_to": "user:alice",
      "assigned_at": "2026-08-22T10:23:11Z",
      "status": "in_review",
      "created_at": "2026-08-22T03:00:00Z",
      "run_id": "rec-001"
    }
  ],
  "next_cursor": null
}

Filter parameters

Parameter	Type	Description
limit	integer (1-200, default 50)	Maximum exceptions to return
cursor	string	Pagination cursor
severity	string	low, medium, high, critical
reason	string	amount_mismatch, date_mismatch, missing_counterparty, duplicate, fx_difference, manual_review
status	string	open, in_review, resolved, escalated
assignedTo	string	me, unassigned, user:<id>, team:<id>
fromDate	ISO 8601 date	Exceptions created on or after this date
toDate	ISO 8601 date	Exceptions created on or before this date

Reason codes

The reason field captures the high-level reason for the match failure:

Reason	Description
amount_mismatch	Amounts differ beyond the rule tolerance
date_mismatch	Dates differ beyond the rule tolerance
missing_counterparty	No matching counterparty in either side
duplicate	Possible duplicate transaction
fx_difference	FX rate differs beyond tolerance
manual_review	Analyst flagged for manual review

Use cases

• Analyst queue UI — populate the exception review queue.
• Escalation dashboard — show all high-severity and unassigned exceptions.
• SLA monitoring — list exceptions older than the resolution SLA.

Code samples

TypeScript

import { FVI } from '@falconveritas/sdk';

const fvi = new FVI({
  baseUrl: 'https://api.falconveritas.com',
  bearer: process.env.FVI_JWT!,
  tenantId: process.env.FVI_TENANT_ID!,
});

const exceptions = await fvi.exceptions.list({
  severity: 'high',
  assignedTo: 'me',
  limit: 100,
});

for (const exception of exceptions.items) {
  console.log(`${exception.id} — ${exception.reason} — ${exception.currency} ${exception.amount_difference}`);
}

Python

from falconveritas import FVI

client = FVI(
  bearer=os.environ["FVI_JWT"],
  tenant_id=os.environ["FVI_TENANT_ID"],
)

exceptions = client.exceptions.list(
  severity="high",
  assigned_to="me",
  limit=100,
)
for exception in exceptions.items:
  print(f"{exception.id} — {exception.reason} — {exception.currency} {exception.amount_difference}")

Related articles

• Resolve exception
• Assign exception
• Exceptions API
• Authentication

Last updated: 2026-08-22 · Page owner: Documentation · Source: src/lib/api/exceptions.ts.