Error handling

  1. Service errors
  2. Errors related to the request schema
    1. Required parameter not specified
    2. The parameter takes an invalid value
  3. Errors related to the request logic
    1. A non-unique identifier is used
    2. An undefined identifier is specified
    3. The specified parameters are incompatible
    4. The specified parameter values are incompatible

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.