Logistics and distribution
Exception codes in logistics: a taxonomy AI agents can use
By SourceX Editorial · Updated
Short answer
Logistics exception codes work for AI agents when they use two levels: a category for what went wrong, such as delay, damage, shortage, refusal or hold, and a cause for why, such as carrier, customer, own facility, external event or data error. Map each note to one category and one cause, keep the original note, and record the resolution.
Key takeaways
- Separate what happened from why it happened; codes that mix the two cannot be analyzed or learned from.
- Keep carrier status reason codes as a source field rather than adopting them as your own taxonomy.
- Replace the catch-all other code with a needs-review flag so unclear cases get resolved instead of hidden.
- An exception record is complete only when it includes the actions taken, the resolution and the cost.
- Original free-text notes stay beside the codes, because the notes carry the reasoning.
Why most exception code lists fail AI agents#
Most logistics exception code lists fail AI agents because they mix what happened with why it happened, overlap with each other and grow by accretion. A list with separate codes for late delivery, carrier late, late due to weather and customer not ready forces whoever is on shift to choose between overlapping answers, and different people choose differently.
The result is a field that cannot be trusted for reporting, let alone for training a model. Teams fall back on free-text notes, which hold the real story but vary in wording, abbreviations and detail from one coordinator to the next.
- Codes that combine an event and a cause, such as late due to weather.
- A catch-all other code that quietly becomes the most common choice.
- Separate lists in the WMS, the TMS and the customer service desk that never reconcile.
- Carrier status codes used as if they explained the root cause.
- Codes added for one customer years ago and never retired.
A two-level taxonomy: category and cause#
A two-level taxonomy assigns every exception one category for what went wrong and one cause for why, and keeps both lists short and stable. The category tells an agent which playbook applies; the cause tells it who should act and who bears the cost.
The illustrative categories below are a starting point, not an industry standard. Rename them to fit your operation, but keep the list small enough that a new coordinator chooses consistently after a short training session.
| Category | What it means | Example from notes |
|---|---|---|
| Delay | Pickup, transit or delivery outside the committed window | Driver stuck at shipper, rolled to next day |
| Damage | Product or packaging harmed in handling or transit | Pallet crushed, cases wet on arrival |
| Shortage or overage | Count received differs from count shipped | Received short against the BOL count |
| Refusal or rejection | Receiver declines all or part of a shipment | Consignee refused, wrong item sent |
| Hold | Shipment stopped for customs, credit, appointment or paperwork | Held at terminal for customs exam |
| Order or pick error | Wrong item, quantity or address created inside the operation | Picked wrong size, reshipped |
| Inventory discrepancy | System quantity differs from physical quantity | Cycle count found location empty |
| Equipment or system | Trailer, reefer, scanner or software failure blocks the work | WMS down during wave release |
- 01Your work records
- 02Personal details removed
- 03You approve the release
- 04Licensed to AI developers
The cause list: who owns the fix#
The cause list answers who owns the fix, which is the question an agent must get right before it drafts a customer message or opens a claim. Causes should name a party or a condition, never an event, so they do not overlap with categories.
Assign the cause after investigation, not at first report. Many delays first logged as carrier problems turn out to be late order releases or appointment errors, and the corrected cause is the valuable part of the record.
| Cause | Examples | Why an agent needs it |
|---|---|---|
| Carrier | Missed pickup, transit delay, damage in transit | Routes the claim and updates the carrier scorecard |
| Shipper or customer | Wrong address, late order release, product not ready | Decides whether a charge is billable |
| Own facility | Mis-pick, labeling error, late wave release | Points to an internal corrective action |
| Third party | Terminal congestion, customs exam, broker paperwork | Sets expectations and who to chase |
| External | Weather, road closure, public holiday | Usually no fault; triggers proactive notices |
| Data or system | Bad master data, EDI mapping error, failed integration | Sends the fix to IT instead of the floor |
How to map free-text notes and carrier codes to the taxonomy#
Mapping free-text notes to the taxonomy works best as a supervised exercise: draft rules, label a sample by hand, compare disagreements and only then automate. The original note is never overwritten; the codes are added beside it.
Carrier status messages, such as the X12 214 shipment status message many carriers send over EDI, carry a status and often a reason. Store the carrier's code as its own source field and map it to your category and cause. The carrier's code describes what the carrier saw; your cause records what your team concluded.
- Pull a representative sample of notes across sites, customers and years.
- Have two experienced coordinators code the sample independently.
- Review every disagreement and tighten the category and cause definitions.
- Write mapping rules for common phrases, abbreviations and carrier codes.
- Run a rules or model first pass on the full history and flag low-confidence cases.
- Send flagged cases to a needs-review queue instead of an other code.
- Re-check a fresh sample periodically and log every definition change with its date.
What a complete exception record contains#
A complete exception record contains the trigger, the codes, the actions taken, the communications and the resolution with its cost. Without the resolution, a record teaches an agent how problems start but not how good teams finish them.
In practice that means an order or shipment ID, the detection time and channel (EDI message, driver call, customer email or WMS alert), the category and cause, the original note, each action with a timestamp, messages to the customer and carrier, the final resolution, the time to resolve, any credit or claim, and a repeat flag. Most fields already exist across the WMS, TMS, help desk and accounting system; the work is joining them.
Adding a short resolution code, such as reshipped, credited, claimed, accepted as is or no action, gives a third dimension for analysis with little extra effort at the desk.
Illustrative: a 3PL recodes its exception history#
Illustrative: a fictional multi-client 3PL runs a WMS for its warehouses, a TMS that receives carrier status messages, and a shared help desk where customer service logs problems. Each system has its own exception list, and the help desk list has grown to dozens of codes, many of them variations of late.
The COO freezes new codes, adopts the eight categories and six causes above, and has two senior coordinators label a sample of notes. A rules-plus-model first pass codes the remaining history, with low-confidence cases sent to review. Carrier codes are kept as a source field.
For the first time, the 3PL can report exceptions by cause across clients, and repeat mis-picks at one building become visible. The coded history also becomes a candidate for licensing, with client and carrier names tokenized and the notes scrubbed and reviewed.
Why coded exception history is licensable, and how SourceX handles it#
Coded exception history is licensable because developers building logistics and customer service agents need real examples of problems and how they were resolved, and a consistent taxonomy makes those examples usable. The original notes remain the most valuable part, since they hold the reasoning.
Protection comes first. Client and carrier names are tokenized consistently so patterns survive, client contracts are checked for limits on shipment data, and free text is scrubbed of names and phone numbers. Presidio's own documentation notes there is no guarantee that automated detection finds all sensitive information, so human review of samples stays in the process.
SourceX treats an exception history as one package within the SourceX five-step transaction: Supply, Rights, Preparation, Approval and Delivery. The history is licensed, not sold, so the company keeps ownership and approves the final scope. The mapping method, definition changes and review samples go into the provenance section of the SourceX Evidence Packet, so a buyer can see how the codes were produced.
Frequently asked questions
How many exception categories should we have?
There is no correct number, but the list should be short enough that coordinators choose the same code for the same situation without looking it up. If two codes are regularly confused, merge them. Detail belongs in the cause, the resolution code and the note, not in an ever-longer category list.
Should we adopt our carriers' status codes as our taxonomy?
No. Carrier codes describe events from the carrier's point of view and vary by carrier and integration. Keep them as a source field and map them to your own category and cause, which reflect what your team concluded after investigating the exception.
Can AI do the mapping for us?
A model can take the first pass, especially on large histories, but it needs clear definitions and a hand-labeled sample to check against. Route low-confidence results to people, and re-check samples whenever definitions change or a new site or client comes online.
Do we have to recode history before licensing it?
Not always. Uncoded notes with clear resolutions can still be useful. Coding makes the history easier to describe, scope and search, and it usually reveals gaps, such as missing resolutions, that are worth knowing before any rights or privacy review begins.
Should warehouse and transportation exceptions share one taxonomy?
Usually yes, with a domain field for warehouse, transportation or customer service. Shared categories and causes let you follow a problem that starts as a mis-pick and ends as a refused delivery, which is exactly the kind of chain an agent needs to learn.
Sources
- Presidio's documentation states that because it uses automated detection there is no guarantee it will find all sensitive information, so additional systems and protections should be employed. Source
Related resources
See if your company qualifies
A short company assessment. No data uploads are needed.