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: falseandcluster_id: null: the domain is not supported for thiscluster_type. - Entries with
success: falseand a message startingResolution 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_idis 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.