Skip to main content

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#

codereason-phrasedescription
301Moved PermanentlyError with request url. Moved permanently
400Bad RequestRequest not processed due to client error
401UnauthorizedAuthentication required
402Payment RequiredPlan Upgrade Required
403Access DeniedYou have no permissions to process the request
404Not FoundThe url you are trying to request not found!
405Method Not AllowedThe method you are trying to call is not allowed!
406Not AcceptableThe target resource does not have a current representation that would be acceptable to the user agent.
413Payload Too LargeThe file you are trying to upload is too big! Try smaller file
500Server ErrorThere is an internal server error with your request.
502Bad GatewayThere 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": [
{...}
]
}