Обработка ошибок

В календарном планировании на все запросы API возвращается ответ в формате JSON и стандартные коды ответов.

В случае редких проблем на серверах Яндекса API ответит сообщением с кодом 50х.

Все ошибки, связанные с валидацией данных или бизнес-логикой, описаны в теле ответа с кодом 200 и должны обрабатываться пользователем.

Ошибки сервиса

В редких ситуациях могут возникнуть проблемы со связью между вашим приложением и серверами Яндекса, а также кратковременные перебои в работе серверов Яндекса.

На случай проблем со связью рекомендуется настроить время ожидания для запросов и ответов в вашем клиенте. 10 секунд должно быть достаточно для сглаживания большей части возможных проблем.

При возникновении проблем на стороне серверов Яндекса вы можете получить ошибку HTTP 5xx. Обычно проблемы на стороне сервера исправляются автоматически через несколько секунд. Чтобы ваше приложение работало, но не создавало повышенной нагрузки на серверы, мы рекомендуем отправлять повторные запросы с растущей задержкой, по принципу экспоненциального затухания со случайной добавкой.

Общее правило:

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

• initial_delay — начальный интервал повтора;
• backoff_multiplier — коэффициент экспоненциального затухания;
• retry — номер попытки;
• jitter — коэффициент при случайной добавке (рекомендуем значение от 0.1 до 0.3);
• rand(1)— равномерно распределенная случайная величина в диапазоне от 0 до 1.

Например, для initial_delay = 1s, backoff_multiplier = 2, jitter = 0.1 получаем:

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

Когда интервал между запросами составит порядка 30–60 секунд, его можно больше не увеличивать. Количество повторных запросов не ограничено.

Координаты

Ошибки в координатах локации

Возможные ошибки:

Типовые ошибки в данных:

• Широта и долгота перепутаны местами.

• Из-за некорректных данных по результатам геокодирования может получиться, что некоторые координаты сильно отличаются от остальных — локация оказалась в другом городе или стране.

Как исправить

Проверить корректность координат локации.

Временные окна

Жесткое окно посещения локации

Локацию нельзя посетить без нарушения окна, а временное окно жесткое.

Возможные ошибки:

Типовые ошибки в данных:

• Окно посещения локации заканчивается слишком рано — в него нельзя успеть без опоздания с учетом указанного времени работы сотрудника и временных окон посещения локации.

• Локация с жестким окном находится слишком далеко — чтобы успеть, нужно выезжать намного раньше. Необходимо указать соответствующее время начала работы сотрудника.

Как исправить

Сделать все окна посещения локаций мягкими, расширить временные окна или использовать оба варианта.

Теги

У сотрудника нет требуемых тегов

Возможные ошибки:

Как исправить

Проверьте правильность написания тегов или добавьте значения в поле employees.tags у сотрудника.

Нет подходящего сотрудника для локации

Для локации указан тег, которого нет ни у одного сотрудника.

Возможные ошибки:

Типовые ошибки в данных:

• В написании тегов допущена опечатка (фактически у локаций и сотрудников тег разный).

• В написании тегов используется разный регистр (теги чувствительны к регистру).

Как исправить

Проверить правильность написания тегов или убрать лишние значения required_tags у локаций.

Геозоны

Локация относится к неподходящей геозоне

Указанной геозоны нет ни у одного сотрудника в allowed_zones (и нет сотрудника без allowed_zones) или есть у всех сотрудников в forbidden_zones.

Возможные ошибки:

Как исправить

Изменить геозоны для сотрудника так, чтобы все локации можно было посетить.

Другие ошибки

Ошибки, связанные со схемой запроса

• Не указан обязательный параметр
• Параметр принимает недопустимое значение

Ошибки, связанные с логикой запроса

• Используется неуникальный идентификатор
• Указан идентификатор, который не определен
• Указанные параметры несовместимы
• Указанные значения параметров несовместимы