🚨 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 with the same payload or parameter made in parallel.
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.

More information can be found in the body of the response in cases of errors.

List of error codes

Below is a list of possible error codes that can be returned in the body of the response, as well as further instructions on how to resolve them.

Code	General description
validation_error	One of the fields is not passing validation. Please refer to the details in message.
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 shipments (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 is usually possible as long as Ship24 didn't find any trace of the shipment. However, it's not possible as soon as Ship24 detects the shipment.
shipping_date_outdated	Trackers with a shippingDate over 180 days old will be rejected, as Ship24 won't track shipments older than 6 months.
parcel_not_found	The shipment can't be found at the moment. It's usually because the shipment has been created recently and the first events are not yet available. Alternatively, you can try to provide more information about the shipment, such as originCountryCode, destinationCountryCode, destinationPostCode, and shippingDate.
request_conflict	The HTTP request conflicts with another request with the same payload or parameter made in parallel and processed concurrently. In such cases, only one request will succeed, and the rest will be in conflict. For idempotent endpoints, the request may be retried later on without impact.
tracker_conflict	A Tracker with similar conflicting parameters already exists. Please try to provide additional parameters, such as shippingDate and destinationCountryCode to differentiate your Tracker.