Intro

This guide walks through common issues you may encounter as you get started with Vizion’s container tracking API. We will touch on questions related to carrier connectivity, invalid data input, webhook failures, and provide solutions to make tracking containers with Vizion as seamless as possible.

No data returned

After making a POST request to track a container, it should take thirty seconds to a few minutes to receive the first update payload. Sometimes there is an underlying issue causing the data to not be received. You can find more information by using the Show Reference Details endpoint to view the last_update_status property.

If the last_update_status is no_data, it is likely because:

• The carrier data is not yet available: If you attempt to track a container before the carrier has generated any data, no information will be returned. Until the carrier provides the necessary data for a container’s journey, no updates can be provided.
• Invalid data input: It is necessary to provide valid data when utilizing the API in order to receive the expected data in return. Make sure to verify you are using the correct carrier code, container ID, or bill of lading when subscribing to references.

If the last_update_status is extraction_failed, it means an interruption in connectivity with the carriers has occurred. Once the connectivity issues are resolved, the data will be updated and received as expect.

<aside> 💡 We always recommend checking our **status page** to see if there are any current issues with a carrier that may explain the extraction failure you are seeing.

</aside>

Using an unsupported carrier

If you attempt to subscribe to a container with an unsupported carrier, you will receive a “Unknown carrier. If you believe this is an error, please contact support” error. Vizion supports a wide range of major carriers and actively incorporates smaller carriers into its system. You can find a comprehensive list of supported carriers here. If you regularly utilize a carrier that is not listed, please reach out to us at [email protected] and let us know as we are always evaluating how to expand our carrier support.

Updates less frequent than expected

Vizion searches for updates every 12 hours. When a new event has been added or a change to the shipment has occurred, you will receive a new update payload. If there is no change to a shipment, an update will not be shared and the last_update_status on the reference will be set to duplicate_payload.

Webhook issues

If you are not receiving update payloads and see webhook_failed for your reference’s last_update_status, this indicates a problem with our ability to access the callback URL you have provided. The best way to troubleshoot and understand the root cause is to examine the logs on your server to determine why it is unavailable. In these cases, Vizion will retry your callback URL at the next update internal. You can always use the Get Reference Updates endpoint to request all updates you might have missed in chronological order. Once the webhook server is available, update payloads will be sent.