Troubleshooting the Tracking API

Introduction

The problems below account for most Tracking API support requests. Work through the section that matches your symptom.

For error codes and response formats, see error management.

Authentication is failing

Check the header format. The value must be Bearer your_api_key, including the prefix and the space. A key sent without Bearer fails.

Check the key is active. Keys are listed in your dashboard under Integrations, API keys. A deleted or rotated key stops working immediately.

Check you are calling the right product. The per shipment and per call products use different endpoints. Calling a per shipment endpoint with a per call subscription fails authentication even though the key is valid. This is the least obvious cause and worth ruling out early. See understanding your API usage and quota for the difference.

No tracking results come back

An empty result is usually correct rather than broken. In order of likelihood:

• The tracking number is wrong, or is an order or reference number rather than a courier tracking number
• The shipment is too new and has not been scanned by the courier yet
• The courier needs information you have not supplied, commonly a destination post code or country code
• The courier you specified is wrong, and auto-detection could not correct it
• The shipment is old enough that the courier no longer returns events for it

See why the shipment status is Pending for each of these in detail, and how to create a good shipment tracker for how to avoid them.

Results come from the wrong shipment

Tracking numbers are not globally unique. Couriers reuse them, and different couriers use identical formats.

Supply a courier code, a destination country, and a shipping date when you create a tracker. Ship24 uses these to discard events that cannot belong to your shipment. If you need to lock tracking to specific couriers, restrictTrackingToCourierCode does that, at the cost of missing a last-mile courier you did not list.

Webhooks are not arriving

• Confirm your endpoint returns 200 OK to a HEAD request, since the URL cannot be saved otherwise
• Confirm your endpoint returns a 2xx to POST requests
• Confirm the shipments have active trackers, because direct lookups generate no webhooks
• If you restrict inbound traffic by IP, confirm the Ship24 outgoing IPs are allowed

Export the webhook history for the shipment. It shows every delivery attempt with status codes and full payloads, which tells you straight away whether Ship24 sent it and what your endpoint replied.

See setting up webhooks for the Tracking API for the full configuration.

Shipments appear to move backwards

Webhook messages are not guaranteed to arrive in chronological order. Compare the event date in each message against the latest event you already hold before updating a status.

Statuses do not match what you expect

Ship24 maps thousands of courier wordings onto a standard set of statuses. See understanding shipment delivery statuses for what each one means, and the status documentation for exact codes.

Still stuck

Contact our support team with the tracker ID or tracking number, the request you sent, and the response you received. Those three things resolve most cases in one reply.

Updated on: 17/08/2026