An Unknown Shipment Status Is a Mapping Gap, Not a Delivery Event

A carrier adds a status code. The integration still returns HTTP 200, but a default branch maps every unfamiliar value to “delivered.” The interface stayed available while the business meaning broke.

The failure is semantic compatibility: a response can be valid JSON and still contain a value the consumer does not understand.

The provider, codes and software below are synthetic. This is a hypothetical adapter design, not a Zenith Eclipse integration or a carrier API specification.

Separate wire validation from interpretation

Validate the envelope first: authenticated source, authorized shipment, field types, payload size and required identifiers. Then interpret the status using a mapping scoped to the provider and contract version.

JSON Schema's enum keyword restricts a value to a fixed set. That is useful when enforcing a closed contract. It also means a newly added code fails an old enum schema. Decide deliberately whether the provider contract is closed or allows future values; do not weaken validation indiscriminately after an error.

For an extensible contract, a bounded string may pass intake while remaining semantically unrecognized. For a closed contract, route the schema violation to a durable exception path. In either case, unfamiliar does not mean delivered, cancelled or delayed.

Return interpretation separately from the raw code

This deliberately small classifier expects the caller to have already established provider identity and the supported contract version.

MAPPINGS = {
    ("demo-carrier", "v1"): {
        "DEP": "departed",
        "ARR": "arrived",
    }
}

def classify(provider, version, raw_code):
    if not isinstance(raw_code, str) or not 1 <= len(raw_code) <= 64:
        raise ValueError("Invalid status-code shape")

    table = MAPPINGS.get((provider, version))
    if table is None:
        return {"kind": "unsupported_contract", "raw": raw_code}

    if raw_code not in table:
        return {"kind": "unmapped", "raw": raw_code}

    return {
        "kind": "mapped",
        "raw": raw_code,
        "milestone": table[raw_code],
        "mapping_revision": "demo-map-1",
    }

assert classify("demo-carrier", "v1", "NEW")["kind"] == "unmapped"
assert classify("demo-carrier", "v2", "ARR")["kind"] == "unsupported_contract"
assert classify("demo-carrier", "v1", "ARR")["milestone"] == "arrived"

Do not trim or uppercase codes unless the provider defines that normalization. Otherwise two distinct values may collapse. Reject malformed shapes; preserve valid unknown strings exactly, with access controls and retention appropriate to the payload.

The mapping above intentionally says “arrived,” not “delivered.” Zenith Eclipse's ocean freight service scope distinguishes port-to-port carriage from wider delivery arrangements. An adapter likewise needs the event location and transport leg before it can associate an arrival with any operational completion. That service page is context, not an API definition.

Keep an unknown event visible without applying it

Persist the original accepted event, classification, provider version and mapping revision. An unmapped event should not update the business milestone or trigger an ERP release action. The dashboard can show the last understood milestone with an explicit unresolved-update indicator and its age.

Do not call the shipment itself delayed merely because interpretation is pending. Report the integration exception separately.

Alert on bounded dimensions such as integration and exception class. Avoid making arbitrary raw codes metric labels: uncontrolled cardinality can make monitoring expensive. Put detailed values in restricted diagnostic records, aggregate counts and route unusual changes to an owner.

Replay meaning under review

When documentation clarifies the new code, review a mapping revision and compare its output against stored fixtures. Keep both the old classification and the new interpretation. Record who approved the change and which events were reprocessed.

Reclassification is not authorization to repeat downstream actions. Use the existing event identity and the consumer's action-deduplication rules. An interpretation change that would reverse a prior action needs an explicit correction workflow.

Test a future code, an unsupported version, an empty string, mixed case, and a known code on the wrong transport leg. A fixture should assert the absence of external effects, not merely the presence of an “unknown” badge.

Compatibility is useful only when it preserves meaning. Accepting an unfamiliar string into a controlled exception queue can be resilient; turning it into a familiar business fact is fabrication.

---

About the publisher: Zenith Eclipse Co works across agricultural commodities, international logistics and machinery sourcing.