Decline reason codes: what to record at the moment of the decision

A decline reason code is the structured statement of why a credit decision went as it did — an artefact the decision produces, in the same transaction as the outcome. What is an adverse action reason code is the narrower question: which specific principal reasons an applicant is told. Both rest on one engineering property. A reason derived later from data that has since moved is a new opinion about an old decision, not a record of it.

What to write in the same transaction as the outcome

• Policy and rule-set version. An identifier for the ruleset that ran, resolvable to its definition, not the name of the current one.
• Model identity and version, with the score and the band boundaries applied. A cutoff moved 6 months later makes yesterday's decision look arbitrary unless the boundary is stored with it.
• The input snapshot. Every value that fed the decision, with source and as-of date — not a pointer to a record that will be updated.
• The triggering conditions, with values. Rule 17 declined is not a reason; unsecured obligations of 2,340 against a threshold of 2,000 is.
• The ordered reason mapping. Which conditions became which applicant-facing statements, in what order, under which mapping version.
• Override and authority. Who could have overridden the decision, whether anyone did, on what basis.
• What was sent. The text delivered to the applicant, stored as delivered, because that is what you get asked about.

A reason recomputed later is a different reason

Every input a credit decision uses is a moving object. A bureau file re-pulled 4 months on shows a settled default, a closed card and 2 new searches; balances have turned over; a document has been replaced by a better copy. Recomputing against that state produces a defensible-looking answer nobody ever gave.

Two inputs need particular care because they are computed rather than fetched. An affordability ratio is a definition as much as a number, so a decline citing debt-to-income is reproducible only if that definition's version is stored beside it — the disagreement in your computed ratio and the underwriter's number. An income figure from bank data carries assumptions about what counted, so record the figure and its basis, not the conclusion, given how easily statement analysis overstates borrower income.

Two vocabularies, and the mapping between them

Internal condition ids and applicant-facing reasons have different lifetimes: one changes when the rule engine does, the other is a sentence a person reads. Keep both on the record with the mapping version, so rewording this year does not rewrite the reasons given last year.

Which reason is the principal one when six rules fire

Conditions usually fail together, and something must decide which are reported and in what order. Do not leave it to the sequence rules evaluate in. Pin the ranking — materiality, then a fixed tie-break — in versioned configuration, so 2 applicants with one profile get the same reasons in the same order, and a ranking change is a dated event rather than a deployment side effect. Wording matters as much as order: a reason naming a specific factor tells the applicant what to change, where a score does not — the emit-an-action-not-a-number rule that also decides whether AI in logistics operations gets used.

A reason the applicant cannot act on is not a reason. It is a score, translated into a sentence, and it helps nobody.

What the rules require of the words themselves

Obligations differ by jurisdiction, and this is engineering guidance rather than legal advice. In the United States, Regulation B — the rule implementing the Equal Credit Opportunity Act, published by the Consumer Financial Protection Bureau — requires notification of action taken on a completed application within 30 days, and the reasons to be specific and principal. Its text treats a statement resting on internal standards, or on failing to achieve a qualifying score, as insufficient; the official interpretation notes that more than 4 reasons is unlikely to help; and reasons must accurately describe the factors actually considered. Confirm the current text with the CFPB, and take advice for each market you lend in.

The engineering consequence is constant wherever the obligation exists: accuracy is achievable only if the system recorded what it used at the time. It is the discipline that keeps a boarded loan honest, where fields are reconciled and stored rather than recomputed — the failure behind a repayment schedule wrong the moment the loan is boarded. Decisioning that emits its own evidence is ordinary AI agents and automation work inside lending and credit operations, part of the finance systems we build.

• lending
• credit decisioning
• auditability
• data modelling