HTTP Errors

HyperTrack adopted the RFC 7807 standard for our error messages.

{
  "status": 404,
  "code": "trip_not_found",
  "title": "Trip could not be found",
  "type": "https://docs.hypertrack.com/#trips-api-trip-not-found",
  "detail": "Trip with the id '00112233-4455-6677-8899-AABBCCDDEEFF' does not exist"
}

With expection to the RFC standard, we are responding with Content-Type: application/json to reduce unexpected behavior when the API returns errors.

The standard requires at least the type property. Everything else is optional. For HyperTrack, we always send title, detail, status, and code in addition. To detail out some errors (for instance multiple invalid fields), the append additional properties as documented in the respective error section.

Parameter	Type	Description
status	Number	HTTP status code
code	String	Error class code
title	String	Brief summary of the error class
type	URL	URL to the respective error page (`about:blank` if none is provided)
detail	String	Detailed description of the error instance
invalid_params	Object	A list of invalid parameters to review (options)

All error messages are in English, as indicated by the Content-Language: en-US header.

Trips API

The Trips API can return one of the following errors. Please review the reference carefully to understand the error reasons and potential steps to overcome the issues faced.

Wrong content-type

{
  "status": 400,
  "code": "wrong_content_format",
  "title": "Wrong content format",
  "type": "https://docs.hypertrack.com/#trips-api-wrong-content-type",
  "detail": "The content submitted in the request body is not in valid JSON format"
}

Potential reasons:

Libraries, functions, and formatters can be used unintnetionally to generate different content formats

Potential actions: Please double check that the body you generate for the request is in valid JSON format.
You can use this small tool to ensure your JSON is valid.

Trip not found

{
  "status": 404,
  "code": "trip_not_found",
  "title": "Trip could not be found",
  "type": "https://docs.hypertrack.com/#trips-api-trip-not-found",
  "detail": "Trip with the id '00112233-4455-6677-8899-AABBCCDDEEFF' does not exist"
}

Potential reasons:

Trip IDs have the same format as Webhook and Devices IDs. You might have mixed up the IDs
Usage of UUID types in database or language could change the formatting (e.g. case sensitivity)

Potential actions: Ensure that the right ID is used - with uppercase letters and no changes to the format(e.g. don't escape the -).

Order not found

{
  "status": 404,
  "title": "Order does not exist",
  "code": "order_not_found",
  "detail": "The requested order does not exist. Please review the invalid parameters",
  "type": "https://hypertrack.com/docs/references/#references-http-errors-trips-api-order-not-found"
}

Potential reasons:

Order IDs might have mixed up the IDs
Usage of IDs in database or language could change the formatting (e.g. case sensitivity)

Potential actions: Ensure that the right ID is used.

Order can not be added

{
  "status": 400,
  "title": "Order can not be added",
  "detail": "Trip is already completed/cancelled. Order can not be added now",
  "code": "wrong_content_format",
  "type": "https://hypertrack.com/docs/references/#references-http-errors-trips-api-order-can-not-be-added"
}

Potential reasons:

Trip in which order is being added would already be completed or cancelled

Potential actions: Ensure that the order additions are done on an active trip only

Order Sequence Can not be Updated

{
  "status": 400,
  "title": "Order sequence can not be updated",
  "detail"" "Trip is already completed/cancelled. Order sequence can not be updated now",
  "code": "wrong_content_format",
  "type": "https://hypertrack.com/docs/references/#references-http-errors-trips-api-order-sequence-can-not-be-updated"
}

Potential reasons:

Trip for which order sequence is being updated would already be completed or cancelled

Potential actions: Ensure that the order sequence updates are done for an active trip only

Order can not be updated

{
  "status": 400,
  "title": "Order can not be updated",
  "details": "Order is already either completed or cancelled",
  "code": "wrong_content_format",
  "type": "https://hypertrack.com/docs/references/#references-http-errors-trips-api-order-can-not-be-updated"
}

Potential reasons:

Order which is being updated would already be completed or cancelled

Potential actions: Ensure that the order updates are done for an active order only

Trip Order Mismatch Error

{
  "status": 400,
  "title": "Order does not belong to this trip"
  "detail": "The requested order does not belong to the provided trip. Please review the paramters",
  "code": "wrong_content_format",
  "type": "https://hypertrack.com/docs/references/#references-http-errors-trips-api-trip-order-mismatch-error"
}

Potential reasons:

Order belongs to a different Trip

Potential actions: Ensure that the order to trip ID mappings are done correctly at your end.

Invalid Order Metadata

{
  "status": 400,
  "title": "Invalid Order Metadata",
  "detail": "Metadata needs to be a valid JSON. Please review the parameters.",
  "code": "wrong_content_format",
  "type": "https://hypertrack.com/docs/references/#references-http-errors-trips-api-invalid-order-metadata"
}

Potential reasons:

Improper escaping of metadata JSON

Potential actions: Ensure that the metadata is a valid JSON.

Order Validation Error

{
  "status": 400,
  "title": "Order request is malformed",
  "detail": "The request format does not have correct format. Please review the invalid parameters",
  "code": "validation_error",
  "type": "https://hypertrack.com/docs/references/#references-http-errors-trips-api-order-validation-error"
}

Potential reasons:

Desitnation without a geometry object is not valid
Geometry types other that Point are not supported
Coordinates in GeoJSON require two float numbers in an array
Radius needs to be a positive integer value
scheduled_at needs to be a string formatted as ISO 8601

Potential actions: Please review and fix the invalid parameters in invalid_params. You can also use this small tool to ensure your request body complies with our JSON schema for the API call.

Device not found

{
  "status": 400,
  "code": "device_not_found",
  "title": "Device could not be found",
  "type": "https://docs.hypertrack.com/#trips-api-device-not-found",
  "detail": "Device with the id '00112233-4455-6677-8899-AABBCCDDEEFF' does not exist"
}

Potential reasons:

The referenced device got remove from HyperTrack systems
Device IDs have the same format as Webhook and Trip IDs. You might have mixed up the IDs
Usage of UUID types in database or language could change the formatting (e.g. case sensitivity)

Potential actions:

Please verify that the referenced device is still available. You can use the Devices API for that
Ensure that the right ID is used - with uppercase letters and no changes to the format(e.g. don't escape the -).

Route not found

{
  "status": 400,
  "code": "route_not_found",
  "title": "Route could not be found",
  "type": "https://docs.hypertrack.com/#trips-api-route-not-found",
  "detail": "Could not generate a route from the device location to the set destination"
}

Potential reasons:

Destination GeoJSON couldn't be geocoded due to a wrong format
No route could be found between the device location and destination

Potential actions:

Ensure that coordinates in GeoJSON have longitude first and latitude second. You can use this small tool to verify your coordinates.
Ensure that there are possible direct connections from the device location to the destination

Validation error

{
  "status": 400,
  "code": "validation_error",
  "title": "Trip request is malformed",
  "type": "https://docs.hypertrack.com/#trips-api-validation-error",
  "detail": "The request format does not have the correct format. Please review the invalid parameters",
  "invalid_params": [
    {
      "name": "destination.geometry.type",
      "reason": "Only supported type is 'Point'. Received 'Polygon' instead"
    }
  ]
}

Potential reasons:

Desitnation without a geometry object is not valid
Geometry types other that Point are not supported
Coordinates in GeoJSON require two float numbers in an array
Radius needs to be a positive integer value
scheduled_at needs to be a string formatted as ISO 8601

Potential actions: Please review and fix the invalid parameters in invalid_params. You can also use this small tool to ensure your request body complies with our JSON schema for the API call.

Completion not possible

{
  "status": 400,
  "code": "completion_not_possible",
  "title": "Trip cannot be completed",
  "type": "https://docs.hypertrack.com/#trips-api-completion-not-possible",
  "detail": "Trip with the id '00112233-4455-6677-8899-AABBCCDDEEFF' cannot be completed"
}

Potential reasons:

The referenced trip has already been completed (status is set to complete)

Potential actions:

Ensure that the referenced trip is in status active. You can use the Get trip by ID endpoint for that

Unauthorized

// HTTP Status: 401
{
  "message": "Unauthorized"
}

Potential reasons:

Authorization header in the request is invalid or missing
Defined a different Authorization strategy than Basic Auth
Base 64 encoding of {AccountId}:{SecretKey} isn't done correctly

Potential actions:

Ensure you follow the API auth guidelines and try cURL to validate the token manually

Route creation failed

{
  "status": 500,
  "code": "route_error",
  "title": "Failed to generate the route",
  "type": "https://docs.hypertrack.com/#trips-api-route-creation-failed",
  "detail": "Server could not complete the route generation"
}

Potential reasons:

HyperTrack systems couldn't process the request at this time

Potential actions:

The request may succeed if you try again sometime later
Reach out to us via email or our customer support slack channel

Devices API

The Devices API can return one of the following errors. Please review the reference carefully to understand the error reasons and potential steps to overcome the issues faced.

Unauthorized

{
  "message": "Unauthorized"
}

HTTP 401 (Unauthorized)

Potential reason: The Authorization header in the request is invalid or missing.

Potential actions:

Review the Auth documentation and try cURL to validate the token manually

Device not found

{
  "status": 404,
  "code": "device_not_found",
  "title": "Device could not be found",
  "type": "https://docs.hypertrack.com/#devices-api-trip-not-found",
  "detail": "Device with the id '00112233-4455-6677-8899-AABBCCDDEEFF' does not exist"
}

HTTP 404 (Not Found)

Potential reasons:

The referenced device got remove from HyperTrack systems
Device IDs have the same format as Webhook and Trip IDs. You might have mixed up the IDs
Usage of UUID types in database or language could change the formatting (e.g. case sensitivity)

Potential actions:

Please verify that the referenced device is still available. You can use the Devices API for that
Ensure that the right ID is used - with uppercase letters and no changes to the format(e.g. don't escape the -).

Method Not Allowed

{
  "status": 405,
  "code": "method_not_allowed",
  "title": "Method Not Allowed",
  "type": "https://docs.hypertrack.com/#devices-api-method-not-allowed"
}

HTTP 405 (Method Not Allowed)

Potential reasons:

The endpoint is not supporting the HTTP method requested.

Potential actions:

Please verify that the referenced HTTP method is supported. You can use the Devices API for that.

Validation Error

{
  "status": 400,
  "code": "validation_error",
  "title": "Device request is malformed",
  "detail": "The request format does not have the correct format. Please review the invalid parameters",
  "validation_errors": [
    {
      "field": "name",
      "message": "Name cannot be empty."
    }
  ],
  "type": "https://docs.hypertrack.com/#devices-api-validation-error"
}

HTTP 400 (Bad Request)

Potential reasons:

The set name was empty. Empty device names will prohibit you from searching, filtering, and sorting by device name in HyperTrack views.

Potential actions:

Please provide a name that is not empty and can uniquely qualify a device

Properties Cannot Be Patched

{
  "status": 400,
  "code": "cannot_patch_property",
  "title": "Properties cannot be patched",
  "detail": "The property {x} is immutable. You can only patch: name and metadata",
  "type": "https://docs.hypertrack.com/#devices-api-properties-cannot-be-patched"
}

HTTP 400 (Bad Request)

Potential reasons:

Fields other than name and metadata were provided in the patch body. The request failed without any changes to the device resource.

Potential actions:

Every field other than name and metadata is immutable on the device resource. Please remove all other fields from the patch body and try again.

Wrong content-type

{
  "status": 400,
  "code": "wrong_content_format",
  "title": "Wrong content format",
  "type": "https://docs.hypertrack.com/#devices-api-wrong-content-type",
  "detail": "The content submitted in the request body is not in valid JSON format"
}

Potential reasons:

Libraries, functions, and formatters can be used unintnetionally to generate different content formats

Potential actions: Please double check that the body you generate for the request is in valid JSON format.
You can use this small tool to ensure your JSON is valid.