# Порожній результат чи помилка API: як розрізнити?

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

Source: https://www.roote.ai/uk/guides/vidchynyj-rezultat-chy-pomylka-api-yak-rozyznyty/
Language: uk
Author: ROOTE

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

Для ROOTE перевірте спочатку HTTP-відповідь, потім бізнес-статус, очікувану колекцію та покриття. Цей підхід запобігає відображенню «немає туалетів», коли виклик Сервісів провалився, або «немає зупинок» після перевищення часу очікування.

## Читання трьох рівнів відповіді

| Рівень | Що перевіряти | Можливі висновки |
| --- | --- | --- |
| Транспорт | Підключення, тайм-аут і HTTP-статус | Чи запит успішний? |
| Контракт | Дійсний JSON, версія та очікувані поля | Чи придатна відповідь для використання? |
| Бізнес-результат | status, collections, coverage, warnings і meta | Що відомо у запитаному периметрі? |

HTTP-код 200 не достатній для підтвердження пошуку. Відповідь може містити статус partial або 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 Сервісів використовує types=toilets; URL карти — modes=toilets. Ці параметри належать до різних контрактів.

Потім розширюйте лише один параметр за раз: збільшуйте радіус у межах маршруту або видаляйте фільтр для явного тесту. Зберігайте початковий запит. Якщо розширюєте автоматично, повідомляйте користувачу новий периметр.

[Побудова пошуку API на основі GPS-координат](https://www.roote.ai/uk/guides/yak-znajty-zupynky-transportu-poblyzy-iz-api-roote/)

## Обробка недоступного джерела без втрати інших

Часткова відповідь може містити місця з джерел, які відповіли, хоча інше не вдалося. Зберігайте ці результати, їхні атрибути і відповідні застереження. Не представляйте список як повний і не замінюйте відсутні поля оманливими значеннями за замовчуванням.

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

## Адаптація повідомлень і відновлення

| Ситуація | Повідомлення для адаптації в інтерфейсі | Дія |
| --- | --- | --- |
| 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/uk/guides/yak-stvoriti-asistenta-yakij-znajde-mobilnist-navkolo-adresi/)

[Розуміння форматів мобільних даних](https://www.roote.ai/uk/guides/gtfs-gtfs-rt-ta-gbfs-yaki-vidminy/)

## Поширені запитання

### Чи доводить порожній список відсутність туалетів?

Ні. Це лише вказує, що за цим пошуком і перевіреними джерелами не отримано результатів.

### Чи можна показати часткову відповідь?

Так, якщо використані сутності валідні і збережено потрібні застереження і ліміти.

### Чи слід повторювати кожну помилку?

Ні. Виправляйте помилки параметрів чи доступу; обмежуйте повтори для тимчасових інцидентів і дотримуйтесь інструкцій сервісу.