Skip to main content

Resolve exception

This recipe shows how to resolve an exception with a chosen remediation action. Resolving an exception creates an immutable audit trail entry and updates the exception status to resolved.

Endpoint​

POST /v1/exceptions/{id}/resolve

Resolves the exception with the chosen remediation action and rationale.

Prerequisites​

  • A valid tenantId and bearer JWT.
  • The user must have at least one of: tenant_admin, tenant_analyst, tenant_remediator.
  • The exception must be assigned to the user (or the user must have tenant_admin role to override).

Request body​

curl -X POST https://api.falconveritas.com/v1/exceptions/exc-001/resolve \
  -H "Authorization: Bearer $FVI_JWT" \
  -H "X-Tenant-Id: $FVI_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "manual_match",
    "rationale": "Bank fee was recorded as separate line item; manually matched to GL entry after verification with operations.",
    "left_transaction_id": "txn-12345",
    "right_transaction_id": "txn-67890",
    "attachments": ["s3://fvi-evidence/exc-001-supporting-doc.pdf"],
    "idempotency_key": "resolve-fvi-$RANDOM"
  }'

Response​

{
  "id": "exc-001",
  "status": "resolved",
  "resolution_action": "manual_match",
  "resolved_by": "user:alice",
  "resolved_at": "2026-08-22T15:30:00Z",
  "audit_trail_id": "audit-001"
}

Resolution actions​

The action field captures the chosen remediation:

ActionDescription
auto_matchConfirm auto-match that should have happened at lower confidence
manual_matchManually match the two transactions
reclassifyReclassify the transaction to a different GL account
write_offWrite off the difference as immaterial
escalateEscalate to senior analyst for further review
deferDefer the exception to a later batch

Audit trail​

Every resolution creates an immutable audit trail entry in the FVI security_events table with the actor, timestamp, before/after state, and rationale. The audit trail entry cannot be modified or deleted.

Use cases​

  • Analyst console — resolve exceptions with one-click remediation.
  • Bulk resolution — resolve multiple exceptions with the same action.
  • Compliance evidence — generate the resolution audit trail for SOC 2 or ISO 27001 evidence.

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 resolution = await fvi.exceptions.resolve('exc-001', {
  action: 'manual_match',
  rationale: 'Bank fee was recorded as separate line item; manually matched to GL entry.',
  leftTransactionId: 'txn-12345',
  rightTransactionId: 'txn-67890',
  idempotencyKey: `resolve-fvi-${Date.now()}`,
});

console.log('Resolved:', resolution.id, 'at', resolution.resolved_at);

Python​

from falconveritas import FVI

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

resolution = client.exceptions.resolve(
  "exc-001",
  action="manual_match",
  rationale="Bank fee was recorded as separate line item; manually matched to GL entry.",
  left_transaction_id="txn-12345",
  right_transaction_id="txn-67890",
  idempotency_key=f"resolve-fvi-{int(time.time())}",
)
print("Resolved:", resolution.id, "at", resolution.resolved_at)

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