Errors

TrackMage uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing, an endpoint is not found, etc.), and codes in the 5xx range indicate an error with TrackMage server.

In the event of a client or server error, the response will contain the standard 4xx or 5xx respectively, accompanied by a description of the error in the Hydra error format or in the format described in the RFC 7807.

Each client library will encapsulate these errors and raise an exception, in addition to other exceptional cases, such as network failures. It is recommended to handle exceptions gracefully.

Common Error Status Codes

code	reason-phrase	description
301	Moved Permanently	Error with request url. Moved permanently
400	Bad Request	Request not processed due to client error
401	Unauthorized	Authentication required
402	Payment Required	Plan Upgrade Required
403	Access Denied	You have no permissions to process the request
404	Not Found	The url you are trying to request not found!
405	Method Not Allowed	The method you are trying to call is not allowed!
406	Not Acceptable	The target resource does not have a current representation that would be acceptable to the user agent.
413	Payload Too Large	The file you are trying to upload is too big! Try smaller file
500	Server Error	There is an internal server error with your request.
502	Bad Gateway	There is a bad gateway server error with your request. Please, try again later.

Responses Examples

Token Not Found

{
  "code": 401,
  "message": "JWT Token not found"
}

Not Acceptable Format

{
  "type": "https:\/\/tools.ietf.org\/html\/rfc2616#section-10",
  "title": "An error occurred",
  "detail": "Requested format \"application\/xml\" is not supported. Supported MIME types are \"application\/ld+json\", \"application\/json\", \"text\/csv\", \"text\/html\".",
  "trace": [
    { ... }
  ]
}

Create Shipment Failed (validation error)

{
  "type": "https:\/\/tools.ietf.org\/html\/rfc2616#section-10",
  "title": "An error occurred",
  "detail": "trackingNumber: Shipment with this tracking number already exists",
  "violations": [
    {
      "propertyPath": "trackingNumber",
      "message": "Shipment with this tracking number already exists"
    }
  ]
}

Internal Server Error

{
  "type": "https:\/\/tools.ietf.org\/html\/rfc2616#section-10",
  "title": "An error occurred",
  "detail": "Something went wrong",
  "trace": [
    {...}
  ]
}

Common Error Status Codes​

Responses Examples​

Token Not Found​

Not Acceptable Format​

Create Shipment Failed (validation error)​