Common issues and steps to troubleshoot

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 Get reference endpoint to view the last_update_status property.

If the last_update_status value 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 value 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.

❗️

Subscribe to the status page

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. You can subscribe by clicking the 'Subscribe to updates' button.

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 contact support 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 property 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 List 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.

Contact support

If you are still encountering issues when attempting to subscribe to containers, please contact support.