# Нет результатов или ошибка API: как отличить?

> Различайте пустой результат, частичный ответ и ошибку API ROOTE. Проверьте координаты, фильтры, покрытие и лимиты для правильного отображения сообщений.

Source: https://www.roote.ai/ru/guides/net-resultat-ou-erreur-api-comment-faire-la-difference/
Language: ru
Author: ROOTE

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

Для ROOTE проверяйте HTTP-ответ, бизнес-статус, ожидаемую коллекцию и покрытие. Это поможет избежать сообщений «нет туалетов» при сбое вызова Сервисов или «нет остановок» при превышении времени ожидания.

## Чтение трёх уровней ответа

| Уровень | Что проверять | Возможные выводы |
| --- | --- | --- |
| Транспорт | Соединение, время ожидания и HTTP-статус | Запрос выполнен успешно? |
| Контракт | Правильность JSON, версия и ожидаемые поля | Ответ пригоден для использования? |
| Бизнес-результат | status, collections, coverage, warnings и meta | Что известно в запрашиваемом диапазоне? |

HTTP-код 200 недостаточен для валидации поиска. Ответ может содержать частичное выполнение или статус error. Ошибка 404 на маршруте не является корректным признаком пустой коллекции: проверьте URL и контракт.

## Понимание success, empty, partial и error

| Статус | Рекомендуемые действия |
| --- | --- |
| success | Отобразить объекты после проверки и сохранить лимиты |
| empty | Сообщить, что по этому запросу не найдено результатов |
| partial | Показать доступную информацию с предупреждениями |
| error | Сообщить, что поиск недоступен; не делать выводов об отсутствии объектов |

Отсутствие результатов относится к запросу и известным источникам. Это не доказывает физическое отсутствие сервиса. Необъемлющее покрытие, строгие фильтры или наложенные лимиты могут уменьшить количество результатов.

## Дерево принятия решений для вашего интерфейса

```
1. La requête a-t-elle abouti ?
   Non → indisponibilité réseau ou délai dépassé.
2. Le statut HTTP est-il acceptable selon le contrat ?
   Non → traiter le code et le message d'erreur.
3. Le JSON respecte-t-il le schéma attendu ?
   Non → réponse inexploitable, jamais "aucun résultat".
4. Le statut métier est-il error ?
   Oui → recherche indisponible.
5. Le statut est-il partial ou la couverture limitée ?
   Oui → résultats utilisables + avertissement.
6. La collection attendue est-elle vide ?
   Oui → aucun résultat retourné dans ce périmètre.
   Non → afficher les résultats et leurs limites.
```

## Проверяйте параметры в правильном порядке

Сначала проверьте широту и долготу, их порядок и полученный город. Затем проверьте единицы радиуса и словарь фильтров. API Services использует types=toilets; карта — modes=toilets. Эти параметры принадлежат разным контрактам.

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

[Формирование API-запроса с помощью GPS-координат](https://www.roote.ai/ru/guides/kak-najti-ostanovki-transporta-ryadom-s-pomoshhyu-api/)

## Обработка недоступных источников без потери других

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

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

## Адаптация сообщений и поведение при повторных попытках

| Ситуация | Сообщение для интерфейса | Действие |
| --- | --- | --- |
| empty | В этом районе с текущими фильтрами нет результатов | Измените район или фильтры |
| partial | Некоторые результаты доступны; поиск неполный | Показывать результаты и предупреждение |
| Ошибка валидации | Поиск содержит неверный параметр | Исправьте запрос |
| Аутентификация или права | Доступ не разрешен для этого поиска | Проверьте аккаунт или токен |
| Лимит или недоступность | Поиск временно недоступен | Следуйте инструкциям по повторным попыткам |

Для 429 смотрите инструкцию сервиса и заголовок Retry-After. Ошибка 400 требует исправления аргументов; повторы не помогут. Не превращайте 401 в автоматический анонимный вызов, если пользователь предоставил токен.

[Справочник ошибок API ROOTE](https://doc.roote.ai/roote-api/errors)

[Статус сервисов ROOTE](https://status.roote.ai/)

## Проверьте все четыре состояния перед публикацией

Подготовьте тестовые ответы — полные, пустые, частичные, ошибочные, JSON с ошибками и тайм-аут. Проверьте отображение, сохранённые результаты и количество повторов. Главное — сбой не должен приводить к заявлению об отсутствии сервисов.

[Применение правил в ИИ-помощнике](https://www.roote.ai/ru/guides/kak-sozdat-pomoshhnika-dlya-poiska-mobilnosti-vokrug-adresa/)

[Понимание форматов данных мобильности](https://www.roote.ai/ru/guides/gtfs-gtfs-rt-i-gbfs-v-chem-raznica/)

## Часто задаваемые вопросы

### Доказывает ли пустой список отсутствие туалетов?

Нет. Он лишь показывает, что для данного запроса и источников нет результатов.

### Можно ли показать частичный ответ?

Да, если используемые объекты валидны и сохраняются предупреждения и лимиты.

### Нужно ли повторять каждый сбой?

Нет. Исправляйте ошибки параметров или доступа; ограничивайте повторы для временных инцидентов и следуйте инструкциям сервиса.