Error handling
In Calendar Planning, all API requests return a JSON response and standard response codes.
In the rare case that an issue occurs on RouteQ 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 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 RouteQ 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 RouteQ 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: Attempt number.jitter: Random increment factor (we recommend values ranging from0.1to0.3).rand(1): Uniformly distributed random variable ranging from0to1.
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)
...
Once the interval between requests is about 30–60 seconds, it no longer needs to be increased. The number of retries is unlimited.
Coordinates
Errors in location coordinates
Possible errors:
| Error text | Explanation |
|---|---|
| Not enough time to visit location (lateness penalty increase is higher than drop penalty): {num} employees | Not enough time to visit a location |
Typical errors in the data:
-
The latitude and longitude are mixed up.
-
Due to incorrect geocoding data, it may turn out that some coordinates are very different from others, and the location may be in another city or country.
How to fix it
Check that the location coordinates are correct.
Time windows
Hard time window to visit a location
You can't visit a location without violating the hard time window.
Possible errors:
| Error text | Explanation |
|---|---|
| Hard time window failed: expected lateness is {sec} seconds | An employee can't get to the destination point on time |
| Failed hard time window of the location | An employee hasn't headed out to the location yet but is already running late |
Typical errors in the data:
-
The time window to visit a location ends too early, and it's impossible to get to the location based on the employee's working hours and the time windows.
-
A location with a hard time window is too far away, and the employee has to depart much earlier to get there on time. An appropriate work start time must be specified for the employee.
How to fix it
Make all time windows to visit a location soft, expand time windows, or both.
Tags
An employee doesn't have the required tags
Possible errors:
| Error text | Explanation |
|---|---|
| Incompatible tags | Incompatible location and employee properties |
How to fix it
Check that the tags are correct or add values to the employee's employees.tags field.
No suitable employee for the location
A location has a tag that none of the employees have.
Possible errors:
| Error text | Explanation |
|---|---|
| Not compatible employees: employee id {id} ref {ref} (+ {N} others) does not have tags required for the location | No suitable employees by tags |
| Not compatible employees: employee id {id} ref {ref} does not have tags required for the location | Employees don't have the appropriate tags |
Typical errors in the data:
-
Tags are misspelled (locations and employees have a different tag).
-
Different cases are used in tags (tags are case sensitive).
How to fix it
Check that tags are spelled correctly or remove unnecessary required_tags values from locations.
Geofences
The location belongs to an inappropriate geofence
No employee has the specified geofence in allowed_zones (and there is no employee without allowed_zones), or all employees have the specified geofence in forbidden_zones.
Possible errors:
| Error text | Explanation |
|---|---|
| Not compatible employees: employees id {id}, ref {ref} does not allowed to visit any of location zones | An employee can't visit the location |
| Location not in the allowed zones | The location is outside of the employee's geofences |
How to fix it
Change geofences for the employee so that they can visit all locations.
Other errors
Errors related to the request schema
- Required parameter not specified
- The parameter takes an invalid value
Errors related to the request logic
- A non-unique identifier is used
- An undefined identifier is specified
- Incompatible parameters
- Incompatible parameter values