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 a 50x code.

All errors related to data validation or business logic are described in the response body with a 200 code and should 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 Yandex servers, 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 retries with progressively longer delays as per the exponential backoff algorithm with random increments.

The general rule:

delay = initial_delay * backoff_multiplier <sup >retry-1</sup> * (1 + jitter * rand(1)), where:

  • initial_delay: Initial repeat interval.
  • backoff_multiplier: Exponential backoff factor.
  • retry: Retry 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, 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)
...

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

Errors related to the request schema

Required parameter not specified

Possible errors:

Error message

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 along with 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 message

Recommendations

Invalid option 'time_zone' provided: '{timezone}'.

Make sure that the options.time_zone parameter has 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 message

Recommendations

Balance_key='{key}' was used more than once in 'balanced_groups' option.

Make sure that all vehicles.shifts.balanced_group_id group IDs in the request are unique.

At least two locations or depots have the same id: {id}.

Make sure that the 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 message

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 message

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 to 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 to use only one of them 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 message

Recommendations

{subject}: 'delivery_deadline' field defined, but only pickups can have it.

{subject}: delivery_to_any field defined, but only pickups can have it.

{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 the pickup orders.

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 one options.location_groups group only.

Time window starts before date from 'options'.

Make sure that 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.
Contact support
Previous
Comparing MVRP and SVRP method groups
Next
Authorization