Container tracking API errors usually occur because of invalid shipment references, authentication failures, request limits, or unavailable carrier data. To troubleshoot a failed request, check the HTTP response, API credentials, and tracking parameters before investigating the carrier's information. With a container tracking API such as Qubictron, developers can also examine the success and status_code fields to distinguish technical failures from missing shipment events. An HTTP 200 response does not always mean that tracking data was successfully retrieved.
The difficult cases are often those where the request completes but the expected shipment history is missing. A container may appear in the shipping line's portal but not in your dashboard, or the carrier may not have published any new events. These situations require a different investigation from an invalid API key or malformed request.
This guide explains how to identify the source of a container tracking API failure, interpret response codes, investigate missing shipment data, and prevent recurring issues in a TMS, customer portal, or logistics application.
Start With Triage: Request or Data?
A ticket that reads "container tracking API not working" tells you nothing yet. Before touching code, find out which of two things happened. If the request failed, the cause usually sits in your integration: credentials, volume, or input. If the request succeeded and returned less than expected, the cause usually sits in the reference you sent, the carrier, or timing.
Symptom | Likely area | First check |
|---|---|---|
401 or 403 response | Credentials or permissions | Key status, plan, environment |
429 response | Request volume | Polling rate, retry loops |
5xx response | Provider or network | Retry with backoff, request ID |
Validation message | Input | Number format, check digit, carrier code |
200 with empty events | Data | Pending status, carrier coverage, reference type |
Events stopped | Source or timing | Last event date, vessel ETA, carrier page |
For every call, log the reference, its type, the carrier code, the timestamp, the HTTP status, the response body, and any request ID the provider returns. Without those fields, the checks that follow turn into guesswork.
How to Read Qubictron API Responses: HTTP Status, Success and Status Code
A container tracking API response contains more information than the HTTP status alone. Qubictron uses the success and status_code fields to describe whether a request succeeded and what happened when shipment data was retrieved. Developers should inspect all three values before deciding how the application should respond.
HTTP | status_code | Meaning |
200 | OK | Tracking information was returned successfully |
200 | NO_EVENTS | The request succeeded, but no tracking events are available |
200 | CARRIER_INFO_NOT_PROVIDED | The carrier has not provided the requested information |
200 | CARRIER_NO_RESPONSE | The carrier did not return the expected response |
200 | CARRIER_NOT_SUPPORTED | The requested carrier is not supported |
400 | WRONG_REFERENCE_NUMBER | The shipment reference is invalid |
401 | INVALID_API_KEY | Authentication failed |
403 | API_KEY_ACCESS_DENIED | The API key does not have permission |
403 | API_KEY_EXPIRED | The API key has expired |
403 | API_KEY_QUOTA_EXCEEDED | The API key's quota has been exceeded |
429 | API_KEY_RATE_LIMIT_EXCEEDED | Too many requests were sent |
500 | UNEXPECTED_ERROR | An unexpected server-side error occurred |
The distinction is particularly important when a request returns HTTP 200 with success: false. For example, a carrier connection problem may produce a response containing:
{
"success": false,
"status_code": "CARRIER_NO_RESPONSE"
}
This is an abbreviated example showing the relevant fields. Your application should treat it differently from NO_EVENTS, where the request may succeed even though the event list is empty. For additional status definitions, consult the official API response codes documentation.
Failed Requests: What the Status Codes Tell You
HTTP status codes follow a shared convention, and providers add their own error bodies on top. Use the code to pick the category and the body to find the cause. Read the container tracking API error codes in your provider's documentation before you write retry logic, because providers differ on which failures are safe to repeat.
401: Authentication Failures
A container tracking API 401 error means the request was not authenticated. Most often the cause is an invalid API key: a typo, a trailing space picked up when the key was pasted, a key that was revoked or rotated, or a test key used against production. Confirm the header name and format your provider expects, then check that the key is active in the dashboard. Do not retry. The same request will fail the same way.
403: Authenticated but Not Allowed
A container tracking API 403 error indicates that the request is not permitted. Qubictron distinguishes several reasons through its status_code field:
API_KEY_ACCESS_DENIED — the API key does not have the required access.
API_KEY_EXPIRED — the key has expired and needs to be renewed.
API_KEY_QUOTA_EXCEEDED — the available request quota has been exhausted.
Check the specific response before taking action. Repeating the same request will not resolve an expired key or exhausted quota. Verify your account permissions and API key status instead.
429: Too Many Requests
A container tracking API 429 error means you are sending requests faster than your plan allows. Slow down, and respect the Retry-After header when the provider sends it. Then fix the cause: polling every container every few minutes, retry loops with no backoff, or a batch job that fires every request at once. Webhooks, where your provider offers them, remove most of the polling load.
500: Server-Side Failures
An HTTP 500 response indicates that the API encountered an unexpected server-side error. In Qubictron, this may be reported as UNEXPECTED_ERROR. Unlike an authentication or validation failure, a temporary server error may resolve without changes to the shipment reference.
Use a limited number of retries with exponential backoff rather than sending requests continuously. Record the HTTP status, application status_code, shipment reference, and request timestamp.
If the problem persists, contact the API provider with the relevant details. Do not assume the shipment itself is responsible for the failure without additional evidence.
Validation Errors: Bad Numbers and Carrier Codes
Most avoidable failures start with the input. Many requests fail because of an invalid container number. A container number has four letters and seven digits, and the last digit is a check digit defined in ISO 6346. Remove spaces and hyphens, convert letters to uppercase, and verify the check digit before the request leaves your system. Then tell the user what is wrong instead of only that something is.
Carrier codes cause the second group. A carrier not supported response means the provider does not cover that shipping line or does not recognize the code you sent. Compare the code with the provider's carrier list, and confirm the container prefix belongs to the carrier you assumed, since leased containers carry the lessor's prefix.
When the Request Succeeds but the Answer Is Thin
Missing shipment data is the harder case, because nothing in the response looks like an error. Work through the causes below in order. Each is cheaper to rule out than the one after it.
When the Carrier Has Not Provided Tracking Data Yet
A successful API request does not guarantee that the shipping line has published shipment events. Qubictron may return NO_EVENTS or CARRIER_INFO_NOT_PROVIDED when the requested information is unavailable. This can happen when a booking has recently been created, the container has not reached its first reported milestone, or the carrier has not supplied the relevant records.
Check the status_code and compare the reference with the carrier's tracking portal. If neither source displays any events, the information may not be available yet. Keep the shipment record active and check again later rather than repeatedly sending immediate requests.
Most importantly, distinguish no events reported from tracking failed in your application's interface.
The Carrier Has Not Published Events
Bookings and Bills of Lading can exist well before a carrier loads events against them, and a carrier's own systems sometimes go down for maintenance, which leaves providers unable to fetch events for a while. When a provider reports container tracking data not available, open the carrier's own tracking page. If it shows nothing either, the gap is upstream, and no change in your code will fill it. Retry later, and tell your user plainly that the carrier has not published information yet.
Wrong Reference, Wrong Carrier
Check the reference type first. A Bill of Lading number sent as a booking number, or the reverse, returns nothing even though both are valid. Then check the carrier. Automatic carrier detection tends to work best for carrier-owned containers. With leased or third-party containers, it can pick the wrong line or return events from an earlier shipment that used the same equipment. If the history looks wrong rather than empty, pass the carrier code explicitly and compare the dates with your booking.
Gaps in the Timeline
Missing tracking events fall into three patterns, and each has a different owner:
Never published. The carrier did not report the event, so only the carrier can fix it.
Published late or out of order. The event exists at the source but reached the provider after your last check. A later poll or webhook delivers it.
Received but lost. The event arrived and your system dropped it, through a failed webhook, an overly aggressive deduplication rule, or an update that could not be matched to your shipment ID.
To find the layer where an event disappears, compare four places: the carrier's page, a fresh response from the provider, the raw webhook payloads you stored, and your database. The first layer that lacks the event is the layer to fix.
A Quiet Status Is Not Always a Fault
A container at sea can go many days without a new event, so a status that has not changed may simply be accurate. Compare the last event date with the vessel's expected arrival before opening an incident. If the arrival date has passed and nothing has moved, escalate with the container number, the carrier, and the last event you hold.
Cross-Checking With a Second Source
When the provider and the carrier disagree, a second source settles the question quickly. Qubictron provides a web tracker and a container tracking API, so the same container can be checked both ways. For one example of how a provider documents its statuses, see the response statuses reference in its documentation.
A Troubleshooting Checklist
Container tracking API troubleshooting goes faster when every ticket carries the same facts:
The container, Bill of Lading, or booking number, and which of the three it is.
The carrier code you sent.
The time of the request and the HTTP status.
The response body and any request ID.
What the carrier's own page shows for the same reference.
With that set, support can usually answer in one reply instead of four.
Preventing the Next Incident
Fixing a single case is routine. The bigger gain comes from design choices that make the same case harmless next time:
Validate early. Check the container number format and check digit before sending anything.
Retry selectively. Retry timeouts, 429, and 5xx responses with backoff. Do not retry 401, 403, or validation failures.
Use supported update methods. Schedule API requests within the provider's rate limits. Use webhooks when the provider supports them and their configuration is documented. Avoid assuming that webhook functionality is available for every tracking API.
Store raw payloads and events. You will need them to show which layer lost an event.
Show distinct states. "Pending," "no events yet," and "failed" mean different things, and your screens should say so.
Wrap the container tracking API in a thin internal layer so error handling and field mapping live in one place. Treat container tracking API errors as product states with their own wording, not as exceptions that leak onto the screen. Good container tracking API troubleshooting starts with this design, because the incident arrives already classified.
Frequently Asked Questions
What does container tracking data not available mean?
It means the provider has no events to return for that reference right now. The cause may be a pending registration, a booking the carrier has not published, a wrong carrier, or a carrier outage. Work through the data checks above in that order.
Should I retry a failed request?
It depends on the code. Timeouts, 429, and 5xx responses are worth retrying with backoff. A 401, a 403, or a validation failure will fail again, so fix the cause first.
Why does a valid container show another shipment's history?
Containers are reused. With leased or third-party equipment, carrier auto-detection can return events from an earlier move. Pass the carrier code explicitly and compare the dates with your booking.
When should I escalate to the provider?
Escalate when the carrier's own page shows events your provider does not, or when the vessel's expected arrival has passed and the status has not moved. Send the reference, carrier code, timestamps, and request ID.