Why detail matters
A summary label makes a dashboard readable but can conceal different causes. Retain the vendor’s original reason code and the reference version used to interpret it. Your internal action should explain which detail mattered.
Unknown codes need a stop rule
If the vendor introduces a new code, route it for review rather than assigning the default favourable action. Keep a small mapping register with documented meanings and owners. Avoid copying an old mapping from another vendor because the words look familiar.
A maintenance exercise
Add a fictional unexpected code to your local fixture. The desired result is a visible exception and no unintended write-back. Then document the actual new code when you have a current source. A familiar colour is not a substitute for a defined meaning.
Put it into practice
A mapping register should preserve the raw code as text rather than replacing it with a friendly label alone. Friendly explanations can help readers, but the original value is needed when documentation changes or support asks what the service actually returned. Add the vendor, observation date, definition reference and internal action. In a fictional update, a vendor adds a previously unseen reason under an existing broad status. The top-level status still looks familiar, but the new reason may change the appropriate review. A default exception rule makes that change visible. Assign one person to review the new meaning and update the mapping deliberately. Do not retroactively rewrite old results without a clear version record. When reporting to a nontechnical colleague, explain the action and uncertainty in plain language while retaining the precise code in the controlled evidence record. If the raw code is blank, preserve that absence and investigate it; a friendly display label must not invent a missing reason.
Sources used for this page
These records support the facts and comparisons above. Merchant-controlled records are labelled so you can separate product claims from independent evidence.
- Bouncer API introduction — Merchant documentation · docs.usebouncer.com · Merchant-controlled · checked 2026-09-27
- ZeroBounce API documentation — Merchant documentation · zerobounce.net · Merchant-controlled · checked 2026-09-27