Please note that when using API Token authentication this header must not be set!
All clients must set the X-Client-Version
header to their applicable Client ID and Version, like MyCustomerApp/1.0.0
. The header
is used for identifying the applicable tenant to enable multi-tenancy, as well as for enabling the expiration of outdated clients.
410 Gone
HTTP response code. Upon this response clients must show
a notification to the user to upgrade their app.400
HTTP response with the unknown_tenant
error code.403
HTTP response code will be returned with the error_code
client_role_mismatch
.
It's up to the client to handle this specific status and error code combination gracefully.X-Deprecated header is returned only on staging if a deprecated endpoint is called, or if a deprecated param is passed.
When a deprecated endpoint is called, this header will have deprecated_action
as value.
If a deprecated param (or params) is passed, then the name of this param will be the value.
Errors are broadly indicated via HTTP status and further narrowed down using an error code in the response payload. Human-readable descriptions are implementor-facing and meant to help in understanding issues, not user-facing.
{
"error_code": "hello_world",
"description": "Some brief description"
}
Some errors like failed validations may contain additional data in the response in order to clarify to the user what was wrong more easily. These messages are localized based on the sent Accept-Language
and should be displayed as applicable:
A validation error response looks like this:
{
"errors": { first_name: ["is blank"] },
"error_code": "validation_failed",
"description": "The request parameters did not satisfy validation rules for this resource."
}
In case the request parameters input is an array, ie. {"invitations": [{ "role": null }]}
the validation error response
will be further grouped by the corresponding items index in the input array, for example:
{
"errors": {
0: { "role": ["is blank"] }
}
}
See documentation for the user invitations endpoint for a more detailed example.
All clients must set the standard Accept-Language
HTTP header explicitly and manually
to the IETF language tag (en-US
)
or ISO639-1 (en
) locale chosen
by the client for client-side message localization.
The reason for this is aligning translated messages stored and shown on the
client side with those from the backend, most notably on validation error messages. For
example if a client supports only en
and de
but the device is actually set fr
, if
the client does not explicitly state which language it picked the backend might make a
differing choice based on available backend languages or configured default fallback
language.
Note that this does not affect "core" translations, which should not be fetched from the backend dynamically but be defined and used in the clients themselves.
Additionally the backend stores the user's current language to use for server-side issued user-facing communication like e-mails and push notifications.
From the total pool of supported languages, only a subset is enabled for any tenant, and one of these is the default locale.
Clients must use only available locales for the tenant, so if a tenant supports en
and de
and
has a default of de
, if fr
is also a MotionTools supported language a client on a device configured to be fr
locale must then fall back to the default locale de
, because fr
is not in the enabled list.
For mobile apps, the default and supported locales are baked in the apps at compile time currently. For web clients the frontend configuration endpoin