HITL (Human-In-The-Loop) classification is iso-compliant's opinionated routing for pain.002 status reports. Every non-ACCP response is classified into one of three outcomes — auto_retry, hitl_required, or final — so the customer-side integration can route the response without re-implementing the ISO 20022 reason-code table.
The classification table lives at apps/api/src/lib/pain002-classifier.ts. The decision is per reason code: AC01 (incorrect account number) and AC03 (invalid creditor account) are typically hitl_required (a human must inspect the beneficiary and correct the input). AC04 (closed account) is final (no retry will succeed). AM05 (duplication) is final (the original transaction already went through). Network-layer transients like TM01 (cut-off time) are auto_retry.
The default classification is conservative — when in doubt, route to HITL. False positives are cheap (a human reviews a payment that could have been auto-retried); false negatives are expensive (a blind retry on AM05 causes a duplicate-payment incident). The customer-side override at POST /v1/iso20022/pain.002/parse?override=... lets a tenant pin a stricter or looser rule per code.
The HITL queue is the customer-side responsibility — iso-compliant returns the classification, the customer's payables system routes the entry to its review UI. The classifier returns reason-code + classification + a one-sentence human-readable explanation, so the queue can present the right context to the reviewer.
A typical production deployment: auto_retry results are exponentially backed off and re-submitted via the same idempotency key (so the bank dedup catches accidental double-fires); hitl_required results land in a per-tenant Slack channel or a payables-review queue; final results trigger a rollback on the customer-side ledger.