Error handling
Even with the best planning, you might encounter errors when integrating with the Shippit API. Here’s how to tackle them:
Common error codes and their meanings
Shippit’s API returns standard HTTP status codes such as 400 Bad Request and 404 Not Found, but it also has custom error codes in the response body.
The most common Shippit error codes are:
| Error Code | Description | Resolution |
|---|---|---|
order_cannot_be_cancelled | The order is in a state where it cannot be cancelled. For example, the order might be in transit. | If the order has not been picked up, contact Shippit support for assistance. |
order_not_found | The specified order tracking number cannot be found in the Shippit system. | Double check the tracking number. If the number is correct and you continue to get this error, contact Shippit support for assistance. |
order_not_available_to_label | The order has not been processed yet and cannot be labelled. | Wait for the order to be processed and try again. |
Labelling errors
If you request a label with the GET /orders/{tracking_number}/label endpoint, and the order is not available to label, the API responds with a 422 Unprocessable Content error. There are several different reasons that you can get this response. They are evaluated in the order given on this page, so if one of these situations matches, it responds with that error without checking further.
label_failed_order_processing
This happens when the order has a status of processing. Order can have this status when there has been a request to update the order, using the Shippit UI, which has resulted in re-quoting and that has not yet completed yet. Updating the pickup, delivery, courier, product fields, or parcel fields can cause re-quoting.
label_failed_missing_courier
This happens if a carrier can’t be allocated to an order, and can happen when the order is created, or updated. In most cases, an order can fall back to the first enabled carrier that offers the requested service level. Sometimes, this fallback doesn’t work, such as an international order where there is no available international carrier. In this case, any labelling request for the order returns this error.
label_failed_invalid_quote
This error occurs when an order has an invalid quote.
Quotes are considered invalid if:
- There is no courier allocated
- The quote is $0
- There is no quote
- There are any errors on the order
This can also happen if the order has a $0 quote, the allocated courier can confirm a $0 quote, and the rules engine filtered the quote.
label_failed_rules_engine
This error occurs if the order was allocated to a plain label carrier, and the order got some quotes, but because of the rules setup by the merchant in the rules engine, it was filtered out.
label_failed_still_generating
This error happens if the allocated carrier can generate label asynchronously. In this case, the labelling process starts in the background, and result in this error.
Currently, this only applies to:
- Australia Post eParcel International
- DHL eCommerce
label_failed_failed_request
This error occurs if the labelling process was started but then failed for some reason. This usually happens because of some external dependency that has failed. For example, if a carrier can’t generate the label
label_failed_tracking_order
If the order has the tracking_only parameter set, any request for a label results in this error.
order_not_available_to_label
This error occurs when none of the previous errors match, but the label is still not available for the order.
Avoiding label request timeouts
If you use an automated order management system, you might find that your label requests time out with a 422 Unprocessable response. There are a range of circumstances that can trigger this response. In some cases, the best workflow is to try and retrieve the label again.
In general, your workflow should create an order, wait one second, then poll for the label. If you receive a 422 error response with one of these messages, and the retry count is less than 8, continue waiting, then try polling for the label again:
order_not_available_to_labellabel_failed_still_generating
If you receive a 422 error response with any other message, check the list in this section to find out next steps.
If the label continues to return a 422 error response, cancel the order using the DELETE /orders/{tracking_number} endpoint, and create the order again.