Skip to content

Exception resolve contract

Canonical partner publication

This file is the canonical external exception-resolve contract (see internal Engineering → Contract sources).

The external contract for exception resolution on the reconciliation exception service: how a resolve request reaches the service, what it contains, and how to read the outcome.

Scope

This page is the external contract only. Detailed engineering design (SQL, concurrency, table layouts) lives on the internal documentation site and is not published here.

Documentation status

Last verified: 26 Sep 2026. Contract behaviour follows the status vocabulary. Confirm the revision in your environment with MasteryHive.

Transport

Path Role Status
Pub/Sub: topic exception-resolution-requests-{env}, drained by the exception service through subscription exception-resolution-requests-sub-{env} Primary trigger in deployed environments. The service starts this pull loop unconditionally at startup; it does nothing when running locally IMPLEMENTED
POST /v1/exceptions/resolve Manual testing / fallback. Mounted in every environment, but the code describes it as a testing channel, not the production path IMPLEMENTED

The service code states the split directly:

  • main.py (startup, lines 112–120): "Exception-resolution Pub/Sub trigger — the primary path. POST /exceptions/resolve (routes/exceptions.py) still exists purely as a local/manual testing channel…"
  • exception_resolution/models.py (lines 161–163): "…the legacy POST /exceptions/resolve route (kept for manual testing) keeps working unchanged…"

Who publishes to the request topic in each environment is agreed with MasteryHive. In the reference design it is the MasteryHive application backend. Outcomes are reported back per resolved cluster as reconciliation-exception update events on the existing exception notification channel; there is no separate "resolution results" topic.

Purpose

Apply an operator decision to the exception clusters in scope. The scope is partner_id + tenant_id + a domain derived from customer_type (and service) + cluster_type, optionally narrowed by cluster_ids. Resolution is partner-wide, not session-scoped: one request can resolve clusters from several reconciliation sessions.

Decisions

decision Meaning
approved Status decision on existing data
rejected Reject the clusters in scope
escalated Escalate the clusters in scope
reopened Reopen previously decided clusters (selects the non-pending band)
reconcile Supply new information (file URLs) and re-ingest and re-match. Used for not_found_gl / not_found_bank

Request fields

The body is the same on both transports.

Field Type Required / default Behaviour
resolution_request_id string Required on Pub/Sub. Optional on HTTP (default null) Idempotency key. On Pub/Sub a message without it is rejected and not acknowledged, so it is redelivered and eventually dead-lettered. On HTTP a missing id is replaced with a random UUID, which gives no retry protection. Always send your own stable id
partner_id string Required Scope
tenant_id string Required Scope
decision enum Required approved, rejected, escalated, reopened, reconcile
customer_type enum Required Accepted values: mfb, commercial_bank, payment_provider, lender, fund_management. Only mfb and commercial_bank are supported; any other value fails validation
service enum or null Default null. Required when customer_type is commercial_bank card_settlement, transfers, cash_deposits, pos_deposits, pos, ussd, bill_payments, atm, nip, other. If omitted, it is taken from template.service; if neither is present, or the value is not recognised, the request fails validation
template object or null Default null Loosely typed reconciliation template. Only template.service is read, as the fallback for service above. Other keys are accepted and ignored by resolution
cluster_type enum Required See Cluster types
note string or null Default null Operator note stored on the audit record
metadata object Default {} Free-form context stored on the audit record
is_recurring boolean Default false Takes effect only when decision is approved and cluster_type is date_difference or amount_mismatch. Each resolved cluster's deviation (date difference in days, or amount difference) is then recorded as a learned value for the recurring-pattern intelligence that can auto-resolve similar future clusters. Ignored in every other case, without error
gl_file_url, bank_file_url list of strings Default [] New source documents for reconcile on not_found_* clusters
mappings list of column mappings or null Default null Caller-confirmed column mapping for the files above. Used on the banking ingest path only
others object or null Default null Additional mapping options. Banking ingest path only
branch_id string or null Default null Explicit branch for a not_found reconcile
cluster_ids list of strings or null Default null Narrows the scope to these clusters. Rejected with decision: reconcile on not_found_gl / not_found_bank, because that path re-matches partner-wide
matching_method enum or null Default null line_by_line, bulk, lump_sum, line_by_line_and_lump_sum. Banking matcher override
amount_tolerance number or null Default null Banking matcher override
recon_time_search_forward, recon_time_search_backward integer or null Default null Banking matcher search windows

The machine-readable schema is the ResolveRequest component in the Reconciliation OpenAPI.

Response (HTTP path)

200 with ResolveResponse:

Field Type Meaning
results list One entry per cluster attempted
results[].cluster_id string or null Cluster id (null for a request-level failure)
results[].session_id string or null The cluster's reconciliation session
results[].success boolean Whether this cluster was resolved. Check it on every entry
results[].new_status string or null Status after the decision
results[].message string or null Failure reason or note
results[].auto_resolved boolean true only for resolutions made by the recurring-pattern automation

HTTP 200 does not mean every cluster was resolved

  • results: []: no clusters matched the scope; nothing changed.
  • A single entry with success: false and cluster_id: null: the domain is not supported for this cluster_type.
  • Entries with success: false and a message starting Resolution failed:: the bulk update failed for those clusters.

Treat a request as complete only when results is non-empty and every entry has success: true.

State transitions

Clusters carry a decision_status band. Resolve selects pending clusters for most decisions, and the opposite band for reopened. The exact status vocabulary and audit fields are internal.

Idempotency

  • Pub/Sub: resolution_request_id is mandatory. The service claims each id atomically. A redelivery of an id that already finished does not re-run the resolution; a redelivery while another instance holds the claim is backed off and retried later.
  • HTTP: the route mints a UUID when the id is missing, so a retried call without an id can resolve twice. Send a stable id.

Errors

Condition HTTP path Pub/Sub path
Invalid enum, unsupported customer_type, missing service for commercial_bank, or cluster_ids with reconcile on not_found_* 422 with the validation message Message not acknowledged; redelivered up to 5 times, then sent to exception-resolution-requests-dlq-topic-{env} (subscriptions as created by the build; existing subscriptions may differ)
Missing resolution_request_id Accepted (UUID minted) Rejected and not acknowledged, as above
No clusters in scope 200, results: [] Acknowledged; nothing changed
Unsupported domain for the cluster type 200, one success: false entry Acknowledged; recorded as failed
Bulk update failure 200, success: false per cluster Acknowledged; recorded as failed or partial
Any other unhandled error 500 Exception resolution failed: … Not acknowledged; redelivered, then dead-lettered

Cluster types

The union across verticals: amount_mismatch, date_difference, possible_bank_fee, fuzzy_narration_match, split_transaction, debit_standalone, extraction_issue, possible_duplicate, needs_review, not_found_gl, not_found_bank, missing_identifier, incomplete_identifier. A value valid for one vertical may match no clusters in another.