container.tracking.failed

Overview

Fired when OpenTrack is unable to locate a container after repeated discovery attempts. This event indicates that the container number could not be found at the specified carrier, and tracking has not successfully started.

When This Event Fires

The container has been stuck in the DISCOVERING phase — OpenTrack has attempted to find the container at the carrier multiple times but the carrier's system does not recognize the container number. After exhausting discovery attempts, this event fires to notify you that the container could not be tracked.

📘
This is different from container.tracking.stopped, which fires for containers that were successfully tracked and have now completed their lifecycle. container.tracking.failed means tracking never successfully started.

Payload Structure

{
  "event": "container.tracking.failed",
  "data": {
    "container": {
      "containerId": "MSCU1234567",
      "masterBill": {
        "number": "MEDU1234567",
        "referenceNumbers": ["PO-12345", "REF-67890"]
      }
    },
    "account": {
      "region": "US",
      "domain": "example.com"
    }
  },
  "deliveryAttempt": 1,
  "pendingRetries": 4,
  "sentAt": "2025-07-19T17:00:00.654Z"
}

⚠️
The data payload for this event is a simplified object — it is not the full IContainerVoyageResponse. It only contains the container identifier, master bill info, and account context.

`data` object fields

Field	Description
`container.containerId`	The container number that failed to track
`container.masterBill.number`	Associated master bill of lading number
`container.masterBill.referenceNumbers`	Array of customer reference numbers associated with the master bill
`account.region`	Account region
`account.domain`	Account domain

Common Use Cases

Use Case	How to Implement
Data quality alert	Notify the operations team that a container number may be incorrect or the carrier assignment is wrong
Retry with corrected data	Prompt the user to verify the container number and carrier, then re-submit tracking
Failed tracking dashboard	Add the container to a "needs attention" list for manual investigation
SLA monitoring	Track how many containers fail discovery to measure data input quality

Updated 1 day ago