> ## Documentation Index
> Fetch the complete documentation index at: https://terminal49.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Tracking Request Lifecycle

> Learn how Terminal49 processes tracking requests through pending, created, and failed states, including retry logic and awaiting_manifest handling.

When you submit a tracking request, your request is added to a queue to be checked with the shipping line. What happens if the request does not go through correctly?

If Terminal49 has difficulty connecting to the shipping line or cannot parse the response, it retries up to 14 times.

This process can take up to approximately 24 hours. You will not receive a `tracking_request.failed` webhook notification until Terminal49 has exhausted the retries, and the `status` field will not be changed to `failed` until then.

## Request number not found / awaiting manifest

If the shipping line returns a response that it cannot find the provided number, Terminal49 either immediately fails the tracking request or keeps trying, depending on the `request_type`:

* **Containers** fail straight away after a not found response from the shipping line.
* **Bill of lading** and **booking numbers** do not fail instantly. The `status` changes to `awaiting_manifest` and Terminal49 keeps checking your request daily. You receive a `tracking_request.awaiting_manifest` webhook notification the first time this happens. If the request number cannot be found after 7 days, the tracking request is marked as failed with the `status` set to `failed` and the `tracking_request.failed` event sent to your webhook.
* To adjust the duration before marking tracking requests as failed, contact [support@terminal49.com](mailto:support@terminal49.com).
* **Incorrect request number type** if the request number type (ex. booking number) is incorrect, the tracking request will still fail even though the request number is correct.

<Tip>
  To reduce tracking failures, use [Auto-Detect
  Carrier](/api-docs/in-depth-guides/auto-detect-carrier) to validate numbers
  and identify the correct SCAC before submitting.
</Tip>

## Failed reason

### Temporary reasons

The `failed_reason` field can take one of the following temporary values:

* `unrecognized_response` when Terminal49 could not parse the response from the shipping line,
* `shipping_line_unreachable` if the shipping line was unreachable,
* `internal_processing_error` when Terminal49 faced another issue,
* `awaiting_manifest` if the shipping line indicates a bill of lading number is found but data is not yet available, or if the requested number could not be found.

### Permanent reasons

Temporary reasons can become permanent when the `status` changes to `failed`:

* `duplicate` when the shipment already existed,
* `expired` when the tracking request was created more than 7 days ago and still has not succeeded,
* `retries_exhausted` if Terminal49 tried 14 times to no avail,
* `not_found` if the shipping line could not find the BL number.
* `invalid_number` if the shipping line rejects the formatting of the number.
* `booking_cancelled` if the shipping line indicates that the booking has been cancelled.
* `data_unavailable` if the number is valid but the shipping line will not provide the data. Examples include shipments that are flagged as private or results that are removed due to data retention policies.

[Failed Reasons when tracking request through dashboard](https://help.terminal49.com/en/articles/6116676-what-happens-after-i-add-a-shipment-to-terminal49-recently-added-shipments#h_ac9b93504f)

## Stopped

When a shipment is no longer being updated then the tracking request `status` is marked as `tracking_stopped`.

You may subscribe to the event `tracking_request.tracking_stopped` for notifications when this occurs.

Terminal49 will stop tracking requests for the following reasons:

* The booking was cancelled.
* The data is no longer available at the shipping line.
* All shipment containers are marked `empty_returned`.
* More than 56 days have passed since the shipment arrived at its destination.
* There have been no updates from the shipping line for more than 56 days.

In addition end-users may stop tracking a shipment through the dashboard.

## Retrieving status

If you want to see the status of your tracking request you can make a [GET request](/api-docs/api-reference/tracking-requests/get-a-single-tracking-request) on what the most recent failure reason was (`failed_reason` field).