🚨 Error management

Ship24 uses conventional HTTP response codes to indicate the success or failure of an API request. Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error caused by the information provided by the client request. Codes in the 5xx range indicate an error with Ship24's servers.

Error response format

Ship24 returns additional information in the HTTP response body when something goes wrong. These appear as an errors array within the response body.

An error has up to two properties:

Property	Description	Example
code	Code describing the error	validation_error
message	If available, a more descriptive message regarding the error.	Please make sure that destinationCountryCode is a valid country code and is in ISO 3166-1 alpha-2 or alpha-3 format.

{
  "errors": [
    {
      "code": "validation_error",
      "message": "Please make sure that destinationCountryCode contains only 2 or 3 characters."
    },
    {
      "code": "validation_error",
      "message": "Please make sure that destinationCountryCode is a valid country code and is in ISO 3166-1 alpha-2 or alpha-3 format."
    }
  ],
  "data": null
}

List of HTTP Status code

Code	Description
200 - OK	Everything worked as expected.
201 - Created	Everything worked as expected.
400 - Bad Request	The request was unacceptable, often due to missing a required parameter.
401 - Unauthorized	No valid API key provided.
402 - Request Failed	The parameters were valid but the request failed.
403 - Forbidden	The API key doesn't have permissions to perform the request.
404 - Not Found	The requested resource doesn't exist.
409 - Conflict	The request conflicts with another request
429 - Too Many Requests	Too many requests hit the API too quickly. We recommend an exponential back-off of your requests.
500, 502, 503, 504 - Server Errors	Something went wrong on Ship24's end.

List of error codes

Below is a list of possible error codes that can be returned, along with additional information about how to resolve them.

Code	General description
validation_error	One of the fields is not passing the validation. Please refer to the details in message
webhook_url_missing	A webhook URL must be set on the Ship24 Dashboard in order to create a tracker.
no_active_subscription	No active subscription (free or paid) allows you to access this resource. Please subscribe to a product allowing the use of this resource.
quota_limit_reached	Your parcels (trackers) or calls usage is above your quota for the billing period.
tracker_not_found	The requested Tracker can't be found. Please make sure it has been created beforehand.
tracker_not_updatable	The Tracker can't be updated. Usually because the shipment corresponding to this Tracker has already been processed. (For example, if you create a Tracker on tracking 123456 on dhl to country US and, due to a data mistake and you wish to change the courier to fedex to country DE, it usually possible as long as Ship24 system didn't found any trace of the shipment. However, it's not possible as soon as Ship24 detected the shipment.
parcel_not_found	The parcel can't found at the moment. It's usually because the parcel has been created recently and that the first events are not yet available. Alternatively, you can try to provide more information about the parcel, such as originCountryCode, destinationCountryCode, destinationPostCode, and shippingDate.