List exceptions

Use this endpoint to retrieve all exceptions. You can filter the results by status, severity, assigned user, external system, and date range. The response uses cursor-based pagination.

GET /v1/exceptions

List exceptions

cURL

curl --request GET \
  --url https://matcher.sandbox.lerian.net/v1/exceptions \
  --header 'Authorization: Bearer <token>'

200

Example

{
  "hasMore": true,
  "items": [
    {
      "createdAt": "2025-01-15T10:30:00Z",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "severity": "HIGH",
      "status": "OPEN",
      "transactionId": "550e8400-e29b-41d4-a716-446655440001",
      "updatedAt": "2025-01-15T10:30:00Z",
      "amount": "1250.50",
      "assignedTo": "[e-mail]",
      "contextId": "550e8400-e29b-41d4-a716-446655440004",
      "currency": "USD",
      "dueAt": "2025-01-20T10:30:00Z",
      "externalIssueId": "RECON-1234",
      "externalSystem": "JIRA",
      "reason": "Amount mismatch detected",
      "resolutionNotes": "Resolved via force match",
      "resolutionReason": "BUSINESS_DECISION",
      "resolutionType": "FORCE_MATCH",
      "resolvedAt": "2025-01-15T12:00:00Z",
      "resolvedBy": "[e-mail]",
      "runId": "550e8400-e29b-41d4-a716-446655440002",
      "settlement": {
        "credited": "95.00",
        "currency": "BRL",
        "difference": "-2.00",
        "expected": "97.00"
      },
      "sourceId": "550e8400-e29b-41d4-a716-446655440003",
      "sourceName": "Bank feed",
      "transactionDate": "2025-01-14T00:00:00Z"
    }
  ],
  "limit": 20,
  "openTotal": 412,
  "overdueTotal": 38,
  "resolvedTotal": 118,
  "total": 530,
  "nextCursor": "eyJpZCI6IjEyMyJ9",
  "prevCursor": "eyJpZCI6IjEyMiJ9"
}

Autorizaciones

Authorization · string · header · requerido

Bearer token authentication (format: "Bearer {token}")

Encabezados

X-Request-Id · string

A unique identifier for tracing the request across services.

Parámetros de consulta

contextId · string<uuid>

Filter by reconciliation context ID (UUID, verified against the tenant; 404 when unknown)

Ejemplo:

"550e8400-e29b-41d4-a716-446655440000"

run_id · string<uuid>

Filter to the exceptions a specific match run surfaced (UUID). Each exception records the LATEST run that touched it, so this returns the breaks that run produced. Legacy rows written before run linkage, and ingestion-minted duplicate-transaction breaks, carry no run id and never match. Absent leaves the listing unfiltered by run.

Ejemplo:

"550e8400-e29b-41d4-a716-446655440002"

status · enum<string>

Filter by status

Opciones disponibles: OPEN, ASSIGNED, PENDING_RESOLUTION, RESOLVED

severity · enum<string>

Filter by severity

Opciones disponibles: LOW, MEDIUM, HIGH, CRITICAL

reason · enum<string>

Filter by exception reason

Opciones disponibles: UNMATCHED, FX_RATE_UNAVAILABLE, MISSING_BASE_AMOUNT, MISSING_BASE_CURRENCY, SPLIT_INCOMPLETE, VALIDATION_FAILED, SOURCE_MISMATCH, DUPLICATE_TRANSACTION, FEE_VARIANCE, FEE_DATA_MISSING, FEE_CURRENCY_MISMATCH, FX_RATE_VARIANCE, AGED_BREAK, OVER_SETTLED

assigned_to · string

Filter by assigned user

Ejemplo:

"[e-mail]"

external_system · string

Filter by external system

Ejemplo:

"JIRA"

search · string

Free-text search across transaction id, reason, and external issue id (case-insensitive substring match)

Ejemplo:

"550e8400"

date_from · string

Filter from date (RFC3339) Filter from date, inclusive lower bound. Accepts an RFC 3339 timestamp or a bare date (YYYY-MM-DD); a bare date is taken at 00:00:00 UTC

Ejemplo:

"2025-01-01T00:00:00Z"

date_to · string

Filter to date (RFC3339) Filter to date, inclusive upper bound. Accepts an RFC 3339 timestamp or a bare date (YYYY-MM-DD); a bare date covers the whole day through 23:59:59.999999999 UTC

Ejemplo:

"2025-01-31T23:59:59Z"

min_age_days · integer<int64>

Filter to exceptions at least this many days old (by created_at). Surfaces aged open-item breaks. 0 (default) disables the filter. Sort by created_at ascending to order oldest-first.

Rango requerido: 0 <= x <= 3650

Ejemplo:

30

cursor · string

The cursor value for retrieving the next page of results. Cursor for pagination (opaque)

limit · integer<int64> · predeterminado: 20

Number of items per page Maximum number of records to return

Rango requerido: 1 <= x <= 200

sort_by · enum<string>

The field used to sort the results. Sort by field. When both sort_by and sort_order are omitted, results use the default queue ordering: status ASC (OPEN, ASSIGNED, PENDING_RESOLUTION, RESOLVED), then created_at DESC, then id DESC. Cursors are bound to the ordering that minted them; switching sort parameters mid-pagination returns 400.

Opciones disponibles: id, created_at, updated_at, severity, status

sort_order · enum<string>

The order used to sort the results. Sort order (engages the explicit single-column sort, by id when sort_by is omitted)

Opciones disponibles: asc, desc

Respuesta

200

application/json

Indicates that the request was successful and the response contains the expected data.

hasMore · boolean · requerido

Ejemplo:

true

items · object[] | null · requerido

Page of exceptions (max 200 per page)

Maximum array length: 200

Show child attributes

limit · integer<int64> · requerido

Rango requerido: 1 <= x <= 200

Ejemplo:

20

openTotal · integer<int64> · requerido

Non-terminal exceptions (OPEN, ASSIGNED, PENDING_RESOLUTION) matching the filter

Ejemplo:

412

overdueTotal · integer<int64> · requerido

Non-terminal exceptions past their due date matching the filter

Ejemplo:

38

resolvedTotal · integer<int64> · requerido

Resolved exceptions matching the filter

Ejemplo:

118

total · integer<int64> · requerido

Total exceptions matching the filter (full set, not the page)

Ejemplo:

530

nextCursor · string

Ejemplo:

"eyJpZCI6IjEyMyJ9"

prevCursor · string

Ejemplo:

"eyJpZCI6IjEyMiJ9"