Error handling

RouteQ VRP API returns JSON in response to all requests and uses standard response codes.

In the rare case that an issue occurs on Yandex servers, the API responds with a message and 50x code.

All errors related to data validation or business logic are described in the response body with a 200 code and must be handled by the user.

Note.

You can see examples of errors in the list below. The list isn't exhaustive.

Service errors

In rare cases, there might be communication issues between your application and Yandex servers or short-term interruptions in the Yandex server operation.

If communication issues occur, we recommend that you configure the waiting time for requests and responses in your client application. 10 seconds are enough to resolve most issues.

If there are any problems on the server, you may get an HTTP 5xx error. Server-side problems are usually fixed automatically within a few seconds. To avoid your application putting increased load on the servers, we recommend sending repeated requests with progressively longer delays as per the exponential backoff algorithm with random increments.

The general rule:

delay = initial_delay * backoff_multiplier ^retry-1 * (1 + jitter * rand(1)), where:

initial_delay: Initial repeat interval.
backoff_multiplier: Exponential backoff factor.
retry: Attempt number.
jitter: Random increment factor (we recommend values ranging from 0.1 to 0.3).
rand(1): Uniformly distributed random variable ranging from 0 to 1.

For example, if initial_delay = 1s, backoff_multiplier = 2, and jitter = 0.1, we get:

retry 1: 1s + 0.1 * rand(1)
retry 2: 2s + 0.1 * 2 * rand(1)
retry 3: 4s + 0.1 * 4 * rand(1)
retry 4: 8s + 0.1 * 8 * rand(1)
...
Copied to clipboard

Once the interval between requests is about 30–60 seconds, it no longer needs to be increased. The number of repeated requests is unlimited.

Errors related to the request schema

Required parameter not specified

Possible errors:


Error text	Recommendations
Error parsing JSON: either 'vehicle' or 'vehicles' is required, see request schema.	Make sure that the required `vehicle`/`vehicles` parameter is defined in the request.
The required option 'time_zone' is not specified in the task.	Make sure that the required `time_zone` field is defined in the request.
{subject}: maximal_stops={count}, but no penalties for extra stops. Please fill shift->penalty->stop_excess.	Make sure that the required `penalty.stop_excess.per_stop` or `penalty.stop_excess.fixed` penalties are defined in the request as well as the maximum number of stops.
{subject}: minimal_stops={count}, but no penalties for missing stops. Please fill shift->penalty->stop_lack.	Make sure that the required `penalty.stop_lack.per_stop` or `penalty.stop_lack.fixed` penalties are defined in the request as well as the minimum number of stops.


Error text	Recommendations
Error parsing JSON: either 'vehicle' or 'vehicles' is required, see request schema.	Make sure that the required `vehicle`/`vehicles` parameter is defined in the request.
The required option 'time_zone' is not specified in the task.	Make sure that the required `time_zone` field is defined in the request.
{subject}: maximal_stops={count}, but no penalties for extra stops. Please fill shift->penalty->stop_excess.	Make sure that the required `penalty.stop_excess.per_stop` or `penalty.stop_excess.fixed` penalties are defined in the request as well as the maximum number of stops.
{subject}: minimal_stops={count}, but no penalties for missing stops. Please fill shift->penalty->stop_lack.	Make sure that the required `penalty.stop_lack.per_stop` or `penalty.stop_lack.fixed` penalties are defined in the request as well as the minimum number of stops.

The parameter takes an invalid value

Possible errors:


Error text	Recommendations
Invalid option 'time_zone' provided: '{timezone}'.	Make sure that the `options.time_zone` parameter takes a value from -12 to 14 or is a string, for example, `Europe/Moscow`.
Invalid date format: {date}.	Make sure that the `options.date` parameter is specified in the `YYYY-MM-DD` format.
{subject}: negative sequence_order value.	Make sure that the `location.sequence_order` parameter is specified as a non-negative integer for all orders.
{subject}: negative shipment volume.	Make sure that the `shipment_size.volume_cbm`, `shipment_size.volume.width_m`, `shipment_size.volume.depth_m`, and `shipment_size.volume.height_m` parameter values are specified as non-negative numbers for all orders.
All vehicle IDs should be either integers or strings. Found {id1} and {id2}.	Make sure that all `vehicles.id` values have the same data type: integer or string.


Error text	Recommendations
Invalid option 'time_zone' provided: '{timezone}'.	Make sure that the `options.time_zone` parameter takes a value from -12 to 14 or is a string, for example, `Europe/Moscow`.
Invalid date format: {date}.	Make sure that the `options.date` parameter is specified in the `YYYY-MM-DD` format.
{subject}: negative sequence_order value.	Make sure that the `location.sequence_order` parameter is specified as a non-negative integer for all orders.
{subject}: negative shipment volume.	Make sure that the `shipment_size.volume_cbm`, `shipment_size.volume.width_m`, `shipment_size.volume.depth_m`, and `shipment_size.volume.height_m` parameter values are specified as non-negative numbers for all orders.
All vehicle IDs should be either integers or strings. Found {id1} and {id2}.	Make sure that all `vehicles.id` values have the same data type: integer or string.

Errors related to the request logic

A non-unique identifier is used

Possible errors:


Error text	Recommendations
Balance_key='{key}' was used more than once in 'balanced_groups' option.	Make sure that all the `vehicles.shifts.balanced_group_id` group IDs are unique in the request.
At least two locations or depots have the same id: {id}.	Make sure that the `id` depot and order IDs don't match in the request.
At least two locations have the same id: {location}.	Make sure that all `id` IDs in the `locations` array are unique.
At least two vehicles have the same ID {id}.	Make sure that all `id` IDs in the `vehicles` array are unique.


Error text	Recommendations
Balance_key='{key}' was used more than once in 'balanced_groups' option.	Make sure that all the `vehicles.shifts.balanced_group_id` group IDs are unique in the request.
At least two locations or depots have the same id: {id}.	Make sure that the `id` depot and order IDs don't match in the request.
At least two locations have the same id: {location}.	Make sure that all `id` IDs in the `locations` array are unique.
At least two vehicles have the same ID {id}.	Make sure that all `id` IDs in the `vehicles` array are unique.

An undefined identifier is specified

Possible errors:


Error text	Recommendations
balanced route group id '{group_id}' is not defined in 'balanced_groups' option.	Make sure that all the group IDs specified in the `vehicles.shifts.balanced_group_id` fields are defined in `options.balanced_groups`.
{subject}: cannot find shift id {shift_id}, specified in '{field}'.	Make sure that all `vehicle.shift_id` shift IDs to which there are links are described in the request.
Cannot find location with id={id}.	Make sure that all `vehicle.shift_id` order IDs to which there are links are described in the request.


Error text	Recommendations
balanced route group id '{group_id}' is not defined in 'balanced_groups' option.	Make sure that all the group IDs specified in the `vehicles.shifts.balanced_group_id` fields are defined in `options.balanced_groups`.
{subject}: cannot find shift id {shift_id}, specified in '{field}'.	Make sure that all `vehicle.shift_id` shift IDs to which there are links are described in the request.
Cannot find location with id={id}.	Make sure that all `vehicle.shift_id` order IDs to which there are links are described in the request.

The specified parameters are incompatible

Possible errors:


Error text	Recommendations
Options 'depot' or 'depots' are mutually exclusive, only one of them should be specified.	The `depot` and `depots` objects are mutually exclusive. Make sure that you use only one of them in the request.
{subject}: fields 'hard_window' and 'hard_time_window' are mutually exclusive, only one of them should be specified.	The `hard_window` and `hard_time_window` fields are mutually exclusive. Make sure that only one of them is in the request.
{subject}: fields 'time_window' and 'time_windows' are mutually exclusive, only one of them should be specified.	The `time_window` and `time_windows` fields are mutually exclusive. Make sure that only one of them is in the request.


Error text	Recommendations
Options 'depot' or 'depots' are mutually exclusive, only one of them should be specified.	The `depot` and `depots` objects are mutually exclusive. Make sure that you use only one of them in the request.
{subject}: fields 'hard_window' and 'hard_time_window' are mutually exclusive, only one of them should be specified.	The `hard_window` and `hard_time_window` fields are mutually exclusive. Make sure that only one of them is in the request.
{subject}: fields 'time_window' and 'time_windows' are mutually exclusive, only one of them should be specified.	The `time_window` and `time_windows` fields are mutually exclusive. Make sure that only one of them is in the request.

The specified parameter values are incompatible

Possible errors:


Error text	Recommendations
{subject}: 'delivery_deadline' field defined, but only pickups can have it.	Make sure that the `delivery_deadline`, `delivery_to_any`, and `delivery_to` parameters are specified only for `pickup` orders.
{subject}: delivery_to_any field defined, but only pickups can have it.
{subject}: 'delivery_deadline' field defined, but only pickups can have it.
Location id {location} is used in more than one location group. Each location can be referenced by only one location group.	Make sure that each order belongs to only one `options.location_groups` group.
Time window starts before date from 'options'.	Make sure that the time windows in the request don't start earlier than the date specified in `options`.
{subject}: hard time window {window1} doesn't contain {window2}.	Make sure that all soft time windows are within the hard time windows.


Error text	Recommendations
{subject}: 'delivery_deadline' field defined, but only pickups can have it.	Make sure that the `delivery_deadline`, `delivery_to_any`, and `delivery_to` parameters are specified only for `pickup` orders.
{subject}: delivery_to_any field defined, but only pickups can have it.
{subject}: 'delivery_deadline' field defined, but only pickups can have it.
Location id {location} is used in more than one location group. Each location can be referenced by only one location group.	Make sure that each order belongs to only one `options.location_groups` group.
Time window starts before date from 'options'.	Make sure that the time windows in the request don't start earlier than the date specified in `options`.
{subject}: hard time window {window1} doesn't contain {window2}.	Make sure that all soft time windows are within the hard time windows.