We made some important changes to the REST API possibly impacting all clients:

  • The API now returns an error_code field when an error is returned. This error code is a normalized code that allows to distinguish programatically errors (the documentation on those error codes is still being worked on). Those error codes follow the format APIXYZ where XYZ is a number. This is added to the already existing HTTP status code, the error description and the error title.
  • An important work has been conducted on all endpoints to rationalize errors returned. There were some cases where incoherent or badly written error messages were returned.
  • A new endpoint /main/v1/errors has been implemented that lists all error codes and their human-readable meaning

Edit: The documentation has been updated to list all errors returned by endpoints. You can find the exhaustive list of errors and their description in the API documentation.

At the same time, in order to help us troubleshoot issues, we kindly request API clients to send a proper User-Agent HTTP header for any API requests. The format we would like all clients to use is the following:

CamelCaseApplicationName/version OS/version [Key/Value]

The more important information for troubleshooting is the application name and version, as such it should come first. Then if possible, having the operating system, device or any specific information in a Key/Value pair would also help. The header should not be too big (keep it under 200 bytes if possible).

Here’s an example:

User-Agent: TicketToRide/2.2.4-487-def4ed5 iPhoneOS/9.1.2 iPadAir2

If you are using the Unity SDK to access the API, this will be implemented for you in the very next release.