Exception workflows

Overview

This article is part of the Exceptions section of the Falcon Veritas Intelligence support center. It is written for engineers, analysts, and tenant admins working with the FVI platform on a daily basis.

Each concept below maps to a specific table or stored procedure in the FVI codebase (Supabase migration set 285 migrations as of 2026-08-22). The full Exceptions reference lives at docs.falconveritas.com/exceptions.

If you are new to Exceptions, start with the Exceptions overview and the core concepts guide. Cross-references to the Troubleshooting, Runbooks, and Security surfaces are inlined throughout.

Prerequisites

• Tenant ID and authentication. You need a valid tenantId and either a publishable key, a JWT issued by Supabase Auth (HS256 or RS256), or a service-role key with a justified call-site.
• Roles. tenant_admin or the role documented as required in the relevant API reference page.
• Browser (for UI flows). Modern evergreen browsers only — last two versions of Chrome, Firefox, Safari, Edge.
• API access (for code paths). Install the SDK of your choice from /api/sdks.html — TypeScript, Python, Go, .NET. Bearer keys are issued via POST /v1/tenants/{id}/api-keys.
• Auditor context. If your call is server-side and crosses tenants, ensure audit logging is wired via the security_events table (see audit trail).

How it works

The flow below shows the canonical path through Exceptions at the FVI platform. Every arrow corresponds to an API call (or to a stored procedure in the supabase/migrations/ tree).

flowchart LR
  A[Source data] --> B[exceptions ingester]
  B --> C[FVI ledger of truth]
  C --> D[Matcher / rule engine]
  D -->|≥ 0.92| E[Auto-match]
  D -->|0.70–0.92| F[Analyst review]
  D -->|< 0.70| G[Exception queue]
  E --> H[Evidence pack]
  F --> H
  G --> H
  H --> I[Audit + retention]
          

Source: supabase/migrations/20260822000001_match_engine_v2.sql and src/lib/reconciliation/exceptions.ts. The full audit paper trail is in the incident response runbook.

Step-by-step

1. Confirm tenant and scope.

   Read your tenant ID from the dashboard URL bar (or call GET /v1/me). Verify the JWT contains https://falconveritas.com/tenants with your tenant in the claim list. Source: src/routes/auth.tsx.

2. Verify preconditions.

   If this flow requires prior data (matches, rules, exceptions), confirm via the exceptions API that the precondition rows exist. Use idempotency keys for any POST.

3. Submit the request.

   Use the SDK of your choice. For raw HTTP, set Authorization: Bearer <jwt> and X-Tenant-Id: <id>. For service-to-service, use the publishable key and let RLS do the tenant scoping (see RLS policies).

4. Confirm the response.

   On success, FVI returns a 2xx with an idempotent identifier. On 4xx, the error code is one of the documented error codes. On 5xx, file an incident per the incident response runbook.

Code samples

curl

curl -X POST https://api.falconveritas.com/v1/exceptions \
  -H "Authorization: Bearer $FVI_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": "$FVI_TENANT_ID",
    "operation": "list",
    "limit": 50,
    "idempotencyKey": "fvi-demo-$RANDOM"
  }'

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 result = await fvi.exceptions.list({ limit: 50 });
console.log(result.items.length, 'items');

Python

from falconveritas import FVI

client = FVI(
    bearer=os.environ["FVI_JWT"],
    tenant_id=os.environ["FVI_TENANT_ID"],
)
items = client.exceptions.list(limit=50)
print(len(items), "items")

Troubleshooting

• Common Exceptions errors
• RLS denied on cross-tenant reads
• Performance issues for large Exceptions jobs
• API error codes

Related articles

• Exception triage
• Exception assignment
• Exception resolution
• Exception workflows

API reference

The endpoints most relevant to this page:

Full OpenAPI 3.1 spec: docs.falconveritas.com/api-reference.