Trakopolis API server implements 2 approaches to error handling:

  • Return HTTP status code with error
  • Return special object with detailed error description

HTTP status codes

This approach is being used for all GET requests and for majority of PUT/POST requests. Trakopolis API server returns following error codes with detailed description in status message, depending on situation:

  • 400 Bad Request.
  • 401 Unauthorized
  • 403 Forbidden
  • 404 Not Found
  • 405 Method Not Allowed
  • 500 Internal Server Error

400 Bad Request is used when client sends malformed request with invalid query parameters.

401 Unauthorized is used when request is valid, but OAuth application doesn't authorized to have an access to Trakopolis API. For example, invalid application credentials were passed (pair of client identifier and client secret) or application has been disabled by Trakopolis or application has not been authorized to have an access to any data at Trakopolis.

403 Forbidden is used when authorized application tries to get an access to division that it doesn't have an access to

404 Not found is used when missing URLs were requested

405 Method Not Allowed is used when application tries to use Put, Post, Delete requests that aren't available for particular entity

500 Internal Server Error is used when something is wrong with our server. It may be temporary or permanent error. If you experiencing such issues permanently, please contact our customer support.

Custom Error Description

Some operations like updating virtual odometer can return errors even if all required request fields were filled properly, application is authorized and access to division is not forbidden. For these situations API server returns special error response instead of real output. Response format can be either XML or Json depending on response-type value in request header.

Response data represent JSON or XML serialized ApiStatusResult object that has 2 string properties:

  • ErrorCode
  • Message

List of supported error codes:

  • Unknown
  • AssetNotFound
  • AssetNoTerminals
  • AssetNoActiveTerminals
  • AssetNoActiveTerminalsMessaging
  • AssetMultipleTerminals
  • AssetTerminalNotFound
  • TerminalNoLocationDateFound
  • WrongDataFormat

The error codes listed above are used for these requests:

  • Set Virtual Odometer
  • Set Hourmeter
  • Send Outgoing Message