pain.002 is the bank's response to a pain.001 or pain.008 submission. It carries one of three top-level statuses (ACCP accepted, PART partially accepted, RJCT rejected) and — for any non-accepted item — a reason code from the ISO 20022 reason-code list.
The reason-code catalog is large (50+ codes) and the customer-side response should differ by code. AC01 (incorrect account number), AC03 (invalid creditor account), BE05 (unrecognised initiating party) are *correctable*: a rebuild + resubmit is safe. AC04 (closed account), AM05 (duplication), MS03 (not specified) require a human in the loop — blind retry will produce a duplicate or a permanent reject.
A common production bug pattern is "retry on any non-success" — that path silently produces duplicate payroll lines on AM05 or wastes cycles on AC04. iso-compliant ships an opinionated classifier at POST /v1/iso20022/pain.002/parse that returns one of: auto_retry, hitl_required, final. See apps/api/src/lib/pain002-classifier.ts for the table.