ISO rejection reasons need a safe escape hatch

What the public implementation shows

The public tests exercise long CoreBank rejection messages across payment responses, status responses, returns, and payee verification. The builders use controlled proprietary reason codes while retaining useful additional explanation where the schema permits it.

The response builders translate unrestricted internal failure text into the constrained code-and-detail structures of ISO 20022. This is the implementation fact behind the note; the architectural reading begins from that visible boundary rather than from an assumed production story.

Operating principleError detail is operationally valuable only when it survives the standard safely and predictably.

The decision behind the mechanism

A stable mapped code carries machine meaning, while bounded supplementary information preserves enough context for investigation without forcing free text into a limited code field.

Passing a long application message directly into a constrained ISO element can fail serialization; dropping it entirely leaves participants with an unexplained rejection. The mechanism matters because it gives that failure a named boundary, durable evidence, and a controlled response instead of leaving the outcome to timing or operator guesswork.

• Map internal failures to stable standard or proprietary reason codes.
• Keep supplementary text within the correct ISO element.
• Remove secrets, stack details, and unsafe characters before transmission.
• Regression-test representative long and unusual failure messages.

How the control should be operated

Maintain an allow-listed reason taxonomy, sanitize additional text, cap its size, and test real failure strings observed at integration boundaries.

Participants receive valid messages that remain actionable, and operations retain the context needed to resolve recurring failures. The reusable lesson is not to copy a class or endpoint in isolation, but to preserve the relationship between identity, state, authority, evidence, and operational ownership.