Error responses

TrackBot Pro uses conventional HTTP response codes to indicate the success or failure of an API request.

In the events of API errors, the HTTP Status Code describes the class of the error that occured. Status codes in the 4xx range indicate that the information provided are invalid (e.g., a required parameter was omitted, a courier slug is not valid, etc.), while codes in the 5xx range indicate an error with TrackBot Pro systems.

An error response contains the status code and a human-readable message describing the error. For some 4xx errors, the response also includes an Error code that explains the cause of the error.

HTTP Status Codes

This table lists the HTTP status codes and the human-readable messages returned by the API (see Examples section).

Status Code	Description	Message
400	Bad Request	The request is invalid. [1]
401	Unauthorized	The API token in the request is missing or is invalid.
402	Payment Required	No active plan for the account or plan doesn't allow API/endpoint usage.
404	Not Found	The requested resource does not exist. [1]
429	Too Many Requests	The API rate limit has been exceeded.
500	Internal Server Error	An unexpected internal server error has occurred.

[1] The actual message returned by the API depends on the error.

Error codes

The error code is a machine-readable string providing details about the cause of some 4xx errors. When an error code is specified, the default message is overridden by a message specific for each error code.

This table lists the error codes and the human-readable messages returned by the API (see Examples section).

Status Code	Code	Message
400	validation_failed	Input parameters validation failed.
400	invalid_courier	The courier slug you specified doesn't exist.
400	shipment_already_exists	A shipment with the same tracking code and courier already exists.

If the error code is validation_failed, the response also includes an errors array listing the validation errors for all the parameters. See the validation failed example below for more information.

Examples

Validation failed

Invalid parameter values have been provided in the request. The errors array contains the list of validation errors for all the parameters.

{
  "error": {
    "status": 400,
    "message": "Input parameters validation failed.",
    "code": "validation_failed",
    "errors": [
      {
        "field": "Limit",
        "message": "'Limit' must be less than or equal to '100'."
      },
      {
        "field": "Page",
        "message": "'Page' must be greater than or equal to '1'."
      }
    ]
  }
}

Invalid courier

The specified courier slug doesn't exist. See the Supported couriers page for more information about supported couriers.

{
  "error": {
    "status": 400,
    "message": "The courier slug you specified doesn't exist.",
    "code": "invalid_courier"
  }
}

Invalid API token

The API token is missing or an invalid one has been provided. See the Authentication page for more information about authenticating API requests.

{
  "error": {
    "status": 401,
    "message": "The API token in the request is missing or is invalid."
  }
}

Too many requests

The API rate limit has been exceeded. See the Rate limits page for more information about rate limiting.

{
  "error": {
    "status": 429,
    "message": "The API rate limit has been exceeded."
  }
}