Shipping integrations have a failure mode that never shows up in your error budget: the status you render is not a sentence, it is the name of a field in somebody else's database. The customer sees BAG_DISPATCH. Support sees a ticket. Nothing threw.
Here are the five shapes this takes in the wild, and four rules that stop them reaching a customer.
The five shapes
1. SCREAMING_SNAKE_CASE - an enum, rendered. On India Post histories you meet ITEM_RECEIVE, ITEM_DISPATCH, BAG_DISPATCH, CUSTOM_RECEIVE, TMO_RECEIVE, plus the mixed-case Bag_Forward. Postal networks move sacks as well as items, so both levels exist in the vocabulary. A bag-level line does not mean the item is untracked; it means the office recorded the container's movement at that moment.
2. camelCase / PascalCase - an API field. Veho, a US last-mile carrier, publishes droppedOffAtVeho, pickedUpFromVeho, PackageArrivedAtFacility, PackageDepartedFromFacility, PackageLoadedOntoFirstMileTransit and bare created. The same network also emits plain-English equivalents on other shipments - arrived at facility, out for delivery - so a single order can contain both spellings of one journey. If your mapping keys on the string, you now have two keys per event and you will discover the second one in production.
3. The doubled word. TIPSA and Cainiao histories carry TRANSITOTRANSITO and REPARTOREPARTO. Read them as two copies of one Spanish word: transito and reparto. That is a code field and a label field concatenated with no separator - which is also why the accent is gone. Treat a string matching ^([A-Z]{4,})\1$ as a loud signal that something upstream joined two fields.
4. Two writing systems, no separator. China Post produces a Chinese template with an English city appended and no space between them. The careful variant of the same event puts the city in full-width brackets instead. If you split on whitespace to find a location, the first form silently gives you one token.
5. The standards string that looks like a bug. Posting/Collection appears character-for-character on histories from China Post, Japan Post, Deutsche Post, Russian Post, Pos Malaysia, Emirates Post, Kenya Post, Bangladesh Post and others. When unrelated operators on different continents emit an identical odd string, that is a shared postal standard, not a carrier quirk - and you should map it once, globally, rather than per carrier.
Scale, for calibration: lines like these are a small minority - under one in three hundred of the tracking lines we see - but they are spread across close to three hundred different carriers. So this is not a special case you can hard-code around for the two carriers you launched with.
Four rules
Rule 1: never render a raw identifier, and never throw it away. Store the carrier's original string and display a normalised status next to it. The original is the only version that is definitely correct; the normalised one is the only version a customer can read. Doing one without the other is how you get either gibberish on the page or a support agent who cannot reproduce what the customer saw.
Rule 2: normalise shape mechanically, vocabulary explicitly. Splitting on capitals and underscores is cheap and fixes most of these. It does not fix abbreviations. Tested on real strings:
const DOUBLED = /^([A-Z]{4,})\1$/; // TRANSITOTRANSITO
const SNAKE = /^[A-Z][A-Z0-9]*(_[A-Z0-9]+)+$/i; // BAG_DISPATCH, Bag_Forward
const CAMEL = /^[a-zA-Z][a-zA-Z0-9]*$/; // droppedOffAtVeho
const title = w => w.charAt(0).toUpperCase() + w.slice(1);
export function looksLikeCode(s) {
if (!s || /\s/.test(s)) return false; // a sentence has spaces
if (DOUBLED.test(s) || SNAKE.test(s)) return true;
return CAMEL.test(s) && /[a-z][A-Z]/.test(s); // needs a case transition
}
export function humanise(s) {
if (!looksLikeCode(s)) return s;
const d = s.match(DOUBLED);
if (d) return title(d[1].toLowerCase());
if (SNAKE.test(s)) return title(s.replace(/_/g, ' ').toLowerCase());
return title(s.replace(/([a-z0-9])([A-Z])/g, '$1 $2').toLowerCase());
}
What it gets right: BAG_DISPATCH to Bag dispatch, droppedOffAtVeho to Dropped off at veho, PackageLoadedOntoFirstMileTransit to Package loaded onto first mile transit, TRANSITOTRANSITO to Transito. What it leaves alone, correctly: Posting/Collection, Pre-Shipment, In-Transit, CONSEGNATA, any CJK string, and - importantly - 1Z999AA10123456784, because a tracking number must never be mistaken for a code to rewrite.
What it gets wrong: TMO_RECEIVE becomes Tmo receive, which is not English either. That is the honest ceiling. Shape is a rule; vocabulary is a table you maintain per carrier.
Rule 3: your status mapping needs a default that is not an error. An unknown status is the normal case on a multi-carrier integration, because carriers add wording without telling anyone. Map unknown to "in transit, details below" and surface the raw line, rather than to UNKNOWN or an exception. A shipment is not broken because your switch statement ran out of branches.
Rule 4: test the strings that must survive untouched. The dangerous bug here is not the gibberish you failed to clean - it is the identifier you cleaned by mistake. Put tracking numbers, hyphenated statuses, CJK strings and single all-caps words (CONSEGNATA) in the test table as negatives, and assert they come out byte-identical.
Why it happens
Every carrier stores an event as a stable identifier plus, usually, a localised sentence per language. The identifier always exists; the sentence sometimes does not. When the sentence is missing for a language, or an integration reads the identifier field by mistake, the identifier is what travels - unchanged - through every hop between the carrier and the customer's screen. That is also why two independent tracking pages can show the same raw string: neither invented it.
If you just want to read one of these rather than build around it: 24hTrack (24htrack.com) is a free package tracker for 3,200+ carriers - paste any tracking number, the carrier is detected automatically, no sign-up. Each carrier's wording is mapped to one standard status and the carrier's original line is kept underneath, which is the same split rule 1 describes. There is also a decoder table for these specific strings in our open guide repo, and a REST + MCP tracking API if you would rather not maintain the mapping yourself.
Disclosure: I work on 24hTrack.
Top comments (0)