Troubleshooting

This section provides reference information and guidance for resolving common issues with your live integration.

Use this guide to diagnose and resolve common operational issues.

Your system can't process the booking file

If you receive errors when parsing the booking CSV file, check these things:

Manually inspect the file. Open the file in a text editor to check for corruption or formatting issues.
Compare the column headings in the file to the structure outlined in the Receive bookings section.

If these steps don't resolve the issue, contact your account manager, or Shippit support.

If you don't see tracking updates on the Shippit platform, check these things:

Check the upload location, and make sure you're uploading to your tracking directory on Shippit's SFTP server.
Check the file contents, and verify that the header row is exactly status,labelNumber,timestamp,reason and that every status value comes from the status code list.
Check whether the file is still in your tracking directory. A file that fails validation stays there, and Shippit records none of its events.

If these steps don't resolve the issue, contact your account manager, or Shippit support.

There are several error codes that the webhook could return:

HTTP code	Description	Action
`401 Unauthorized`	The authorisation header is missing, or the credentials are incorrect	Verify the credentials you are using
`400 Bad Request`	The request body isn't valid JSON, or the carrier code in the endpoint URL isn't recognised	Check the carrier code in your endpoint URL, then compare the payload to the structure outlined in the Send tracking section.
`403 Forbidden`	Your account isn't set up for webhook tracking	Contact Shippit support. Retrying doesn't clear this.
`5xx Server Error`	A temporary issue on Shippit's side	Retry with exponential back off. If failures persist for over 30 minutes, check the Shippit Status Page, or contact Shippit support.

Shippit validates the payload after responding, so a 202 confirms the request arrived, not that Shippit applied the event. Check these things:

Confirm the labelNumber or consignmentNumber matches a package Shippit sent you.
Confirm every required field is present.
Confirm the status value comes from the status code list.

If these steps don't resolve the issue, contact your account manager, or Shippit support.