Blog
Container Tracking Prefix Errors: Causes and Solutions
Container tracking prefix issues are one of the most common reasons your API requests may not return results, even when the container number looks perfectly fine
A Container Tracking API is designed to help you monitor shipments worldwide. Most users expect it to be as simple as entering a container number and getting real-time data, and usually, it is.
But sometimes, things get tricky, especially when multiple shipping lines share the same prefix. In this post, we’ll break down how container tracking prefix confusion happens and how to fix it using the JsonCargo API.
What Are Container Tracking Prefixes?
Every shipping container has a unique identifier that starts with a four-letter prefix (e.g. MSCU, CCLU, etc.), typically linked to a specific shipping line. In a perfect world, that prefix would tell you exactly who operates the container.
But in reality? It’s messier than that.
Some prefixes are shared across multiple shipping lines, especially when containers are leased or operated through logistics partnerships.
For example, a container starting with CCLU might belong to COSCO, CMA CGM, or even another carrier entirely. So simply searching by container number alone won’t be enough to pinpoint the actual carrier.
Imagine this:
You’re a logistics manager tracking a container with the number CCLU1234567. You plug it into the JsonCargo Container API, expecting to get status updates — but instead, you get a 404 error.
The prefix “CCLU” looks like it should belong to one specific carrier, right?
But here’s the twist: CCLU is used by multiple shipping lines, including COSCO, CMA CGM, and others. Because these carriers often lease or interchange containers, the prefix alone doesn’t uniquely identify the operator.
How to Track Containers with Shared Prefixes?
To handle these shared scenarios, the JsonCargo Container API requires you to explicitly include the shipping line in your request. Otherwise, your request may return incorrect data — or even a 404 Not Found.
GET https://api.jsoncargo.com/api/v1/containers/CCLU1234567?shipping_line=COSCO
That extra shipping_line parameter tells the system exactly which database to pull from and just like that, the tracking works.
Common Container Tracking API Errors (And How to Fix Them)?
Upon checking your API request and why probably is not returning any result, you need to double-check that your request isn’t hitting one of these common roadblocks:
Incorrect Container Number: Double-check the full code (e.g. CCLU1234567). Typos are more common than you think.
Missing or Incorrect Shipping Line Name: Especially important if the prefix is shared, make sure the name is spelled correctly.
Missing, Invalid or Expired API Key: Always include your API key in the request headers.
Rate Limit Exceeded: If you’ve hit your quota, your requests will be blocked. You can check usage stats via our API Key Usage Endpoint.
Expired Subscription: Make sure your plan is active and payments are up to date.
Top Mistakes Developers Make When Using Container Tracking API:
While setting up your code and starts using the container tracking API, you’d need to make sure that you are not doing the following mistakes:
❌ Using a container tracking prefix without specifying the shipping line
❌ Leaving out the API key
❌ Using an expired key or hitting rate limits
❌ Misspelling shipping line names (e.g. cma-cgm instead of cma_cgm)
❌ Forgetting to URL-encode special characters
Common Container Tracking Questions You Can Get While Use JsonCargo API:
Can I track a container without knowing the shipping line?
If the prefix is unique and you are sure about that, it will work and you can use our Get Container Details endpoint without the need to specify the Shipping Line.
If the container prefix is used by multiple carriers. If the prefix is unique, it might work, but for third-party prefixes, always include the shipping_line parameter.
How do I find the shipping line for my container?
Check your original shipment booking, Bill of Lading, or ask your freight forwarder. If you’re regularly working with containers, maintain a prefix-to-carrier map in your system.
By understanding how container tracking prefixes work and following best practices in your API requests, you can significantly improve your container tracking accuracy and reduce debugging time.
Need more help? Check our API docs or reach out to our support team for implementation support.