---
metadata:
  - name: generator
    content: Diplodoc Platform v5.52.0
alternate:
  - https://yandex.kz/routing/doc/en/vrp/error-handling.md
  - https://yandex.kz/routing/doc/kk/vrp/error-handling.md
  - https://yandex.kz/routing/doc/ru/vrp/error-handling.md
  - href: en/vrp/error-handling.md
    type: text/markdown
    title: Markdown version
  - href: llms.txt
    type: text/markdown
    title: llms.txt
title: RouteQ — API integration — error handling
---
> **Documentation Index:** Fetch the complete configuration index at https://yandex.kz/routing/doc/en/llms.txt


# 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](https://yandex.kz/routing/doc/en/vrp/get-result.md) with a 200 code and should be handled by the user.


{% note info %}

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

{% endnote %}

## Service errors {#service-unavailable}

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](https://en.wikipedia.org/wiki/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`: 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, `jitter` = 0.1, we get:

```bash
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 {#errors-schema}

### Required parameter not specified {#required-object}

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.||
|#

### The parameter takes an invalid value{#invalid-format}

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.||
|#


## Errors related to the request logic {#errors-logic}

### A non-unique identifier is used {#not-unique-id}

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.||
|#

### An undefined identifier is specified {#not-defined-id}

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.||
|#

### Incompatible parameters {#incompatible-params}

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.||
|#

### Incompatible parameter values {#incompatible-values}

Possible errors:

#|
||**Error text** | **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 `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 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.||
|#


<!-- source: en/vrp/_includes/feedback.md -->
<a href="feedback">
  <span class="button">Contact support</span>
</a>


<!-- endsource: en/vrp/_includes/feedback.md -->