Warnings Registry

The closed registry of conversion warning codes. Every lossy or assumed step in a conversion surfaces as one of these — nothing is dropped silently.

The contract

Converting between formats with different capacities sometimes forces a choice: truncate a name to fit an MT line, default a mandatory timestamp the source never carried, transliterate a character the SWIFT X charset can't hold. transmute's contract is that every such step emits a structured warning — if the warnings[] array carries no lossy entries, nothing was dropped.

{ "code": "TRUNC_NAME", "severity": "lossy",
  "sourceField": "payment.creditor.name", "targetField": ":59:",
  "detail": "name shortened from 52 to 35 characters to fit the MT line budget" }

Field	Meaning
`code`	A stable identifier from the closed registry below — match on this
`severity`	`info` < `warning` < `lossy` < `error`
`sourceField` / `targetField`	Paths naming what was affected
`detail`	A short explanation — never message content values

Warnings are deterministic (sorted by source field, then code) — identical input yields identical warnings, so you can diff them across runs.

On bare-document responses (Accept: application/xml/text/plain) warnings can't ride in the body; you get an X-Transmute-Warnings count header instead — re-issue with Accept: application/json for the entries. Warnings are not stored server-side.

Severity semantics

Severity	Meaning	Recommended handling
`info`	An assumption or normalization was made; no data lost	Log it
`warning`	Something didn't verify or is structurally imperfect	Review in reconciliation
`lossy`	Data present in the source is absent or reduced in the target	Review item — decide whether the loss matters for your flow
`error`	Reserved for strict-mode style failures	Fail the item

Setting options.strict: true on convert turns would-be lossy outcomes into failures.

The registry

The registry is closed: codes are only ever added (with release notes), never renamed or silently changed, so switching on them exhaustively is safe.

Lossy by default

Code	Emitted when
`CHARSET_TRANSLIT`	Characters were transliterated to the SWIFT X charset (e.g. `ü` → `ue`)
`CHARSET_DROP`	Characters with no transliteration were replaced or removed
`TRUNC_NAME`	A party/agent name was cut to fit the MT line budget
`TRUNC_ADDRESS`	Address components were dropped or cut flattening to MT lines
`TRUNC_REMITTANCE`	Remittance text exceeded `:70:`/`:86:` capacity
`TRUNC_REFERENCE`	A reference exceeded the target field length
`DROP_FIELD`	A whole source element has no slot in the target format
`DROP_AGENT`	An agent in the chain cannot be represented in the target
`OVERRIDE_SUPPRESSED`	A tenant override rule deliberately dropped this field (always paired with `OVERRIDE_APPLIED`)

Warning by default

Code	Emitted when
`AMOUNT_MISMATCH`	Charges arithmetic or a page balance chain failed verification
`ADDRESS_UNSTRUCTURED`	A structured address was preferred but only unstructured was available

Info by default

Code	Emitted when
`PAGED_OUTPUT`	Output was split into N MT pages (2,000-character cap per message)
`MISSING_REQUIRED_DEFAULTED`	A mandatory target element was defaulted (e.g. camt.053 `CreDtTm` from an MT940 that carries no timestamp)
`CODE_UNMAPPED_PROPRIETARY`	A code had no table mapping and was carried as proprietary
`DATE_YEAR_INFERRED`	An `:61:` entry-date year was inferred from the value date
`RETURN_REASON_UNMAPPED`	A return/cancellation reason code had no mapping row; carried as proprietary/narrative
`CHARGES_DETAIL_UNMAPPED`	A charges detail line had no mapping row; carried as narrative/verbatim
`OVERRIDE_APPLIED`	A tenant override rule changed this field's mapping (detail names the action, never values)
`CHARGES_DUPLICATED`	A return charge restated in two source fields of equal amount was collapsed to one, not double-counted
`ACCOUNT_CCY_SUFFIX`	An MT `:25:` account id carried a trailing currency suffix (a known bank dialect); split into IBAN + account currency

Using warnings in pipelines

Persist the codes (they're metadata, safe to store) alongside your own record of each conversion.
Alert on lossy in flows where completeness matters — payment chains, regulatory reporting.
Don't string-match detail — it's for humans and may be refined; code is the contract.

Was this page helpful?