# Brak wyniku czy błąd API: jak je rozróżnić?

> Rozróżnij pusty wynik, odpowiedź częściową i błąd API ROOTE. Sprawdź współrzędne, filtry, pokrycie i ograniczenia, aby wyświetlić właściwy komunikat.

Source: https://www.roote.ai/pl/guides/brak-wyniku-czy-blad-api-jak-roznicowac/
Language: pl
Author: ROOTE

API bez wyniku i API z błędem wymagają dwóch różnych działań. Udane zapytanie może nie zwrócić żadnego miejsca w przeszukiwanym obszarze. Natomiast błąd sieci, osiągnięcie limitu lub niedostępne źródło uniemożliwiają wyciągnięcie wniosków z wyszukiwania.

Dla ROOTE najpierw sprawdź odpowiedź HTTP, potem status biznesowy, oczekiwaną kolekcję i pokrycie danych. Podejście to zapobiega wyświetlaniu „brak toalety”, gdy wywołanie Usług zawiodło lub „brak przystanku” po przekroczeniu czasu oczekiwania.

## Odczytanie trzech poziomów odpowiedzi

| Poziom | Co kontrolować | Możliwe wnioski |
| --- | --- | --- |
| Transport | Połączenie, czas oczekiwania i status HTTP | Czy żądanie się powiodło? |
| Kontrakt | Poprawny JSON, wersja i oczekiwane pola | Czy odpowiedź jest użyteczna? |
| Wynik biznesowy | status, kolekcje, pokrycie, ostrzeżenia i meta | Co wiadomo o żądanym obszarze? |

Kod HTTP 200 nie gwarantuje poprawnej wyszukiwarki. Odpowiedź może zawierać wykonanie częściowe lub status error. Natomiast 404 dla trasy nie jest normalnym sposobem oznaczania pustej kolekcji: sprawdź URL i kontrakt.

## Zrozumienie success, empty, partial i error

| Status | Zalecane działanie |
| --- | --- |
| success | Wyświetl encje po walidacji i zachowaj limity |
| empty | Poinformuj, że wyszukiwanie nie zwróciło wyników |
| partial | Wyświetl dane użyteczne z odpowiednimi ostrzeżeniami |
| error | Przedstaw, że wyszukiwanie jest niedostępne; nie wyciągaj wniosku o braku miejsc |

Brak wyniku dotyczy zapytania i znanych źródeł. Nie dowodzi fizycznego braku usługi. Niepełne pokrycie, restrykcyjny filtr lub nałożony limit mogą zmniejszyć liczbę wyników.

## Drzewo decyzyjne dla twojego interfejsu

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

## Sprawdzaj parametry we właściwej kolejności

Najpierw zweryfikuj szerokość i długość geograficzną, ich kolejność oraz uzyskane miasto. Następnie sprawdź jednostkę promienia i słownictwo filtrów. API Usługi używa types=toilets; URL mapy używa modes=toilets. Te parametry należą do różnych kontraktów.

Następnie rozszerzaj pojedynczy wymiar po kolei: zwiększ promień w granicach trasy lub usuń filtr dla wyraźnego testu. Zachowaj ślad zapytania początkowego. Jeśli rozszerzasz automatycznie, poinformuj użytkownika o nowym obszarze.

[Budowanie zapytania API wokół współrzędnych GPS](https://www.roote.ai/pl/guides/jak-wyszukac-przystanki-komunikacji-w-poblizu-z-uzyciem-api/)

## Obsługa niedostępnego źródła bez tracenia innych

Odpowiedź częściowa może zawierać miejsca ze źródeł, które odpowiedziały, podczas gdy inne zawiodły. Zachowaj te wyniki, ich przypisania i istotne ostrzeżenie. Nie przedstawiaj listy jako kompletnej i nie zastępuj brakujących pól wprowadzającymi w błąd wartościami domyślnymi.

Starsze informacje przechowywane w pamięci podręcznej mogą być przydatne, jeśli polityka na to pozwala. Muszą być jednak oznaczone jako przestarzałe. Czas otrzymania twojego zapytania nie odświeża oryginalnej obserwacji.

## Dostosowanie komunikatów i sposobów obsługi

| Sytuacja | Komunikat do dostosowania w interfejsie | Działanie |
| --- | --- | --- |
| empty | Brak wyników w tym obszarze z podanymi filtrami | Zmień obszar lub filtry |
| partial | Dostępne są niektóre wyniki; wyszukiwanie jest niekompletne | Wyświetl wyniki i ostrzeżenie |
| Błąd walidacji | Zapytanie zawiera nieprawidłowy parametr | Popraw zapytanie |
| Uwierzytelnianie lub uprawnienia | Ten dostęp nie pozwala na takie wyszukiwanie | Sprawdź konto lub token |
| Limit lub niedostępność | Wyszukiwanie jest tymczasowo niedostępne | Przestrzegaj zasad ponawiania |

Dla 429 sprawdź zasady usługi i ewentualny Retry-After. Błąd 400 wymaga korekty argumentów; powtarzanie tego samego zapytania nic nie zmieni. Nie zmieniaj 401 w automatyczne anonimowe wywołanie, jeśli użytkownik dostarczył token.

[Referencje błędów API ROOTE](https://doc.roote.ai/roote-api/errors)

[Stan usług ROOTE](https://status.roote.ai/)

## Testuj cztery stany przed publikacją

Przygotuj kompletne, puste, częściowe i błędne odpowiedzi testowe, a także niepoprawny JSON i przekroczony limit czasu. Sprawdź komunikaty wyświetlane, zachowane wyniki i liczbę ponowień. Kluczowy test to, aby awaria nigdy nie wskazywała na brak usług.

[Stosowanie tych zasad w asystencie AI](https://www.roote.ai/pl/guides/jak-stworzyc-asystenta-mobilnosci-przy-adresie/)

[Zrozumienie formatów danych mobilności](https://www.roote.ai/pl/guides/gtfs-gtfs-rt-i-gbfs-jakie-sa-roznice/)

## Najczęściej zadawane pytania

### Czy pusta lista dowodzi braku toalet?

Nie. Informuje tylko, że nie zwrócono wyników dla tego zapytania i przeszukanych źródeł.

### Czy można wyświetlić odpowiedź częściową?

Tak, jeśli używane encje są ważne i zachowasz ostrzeżenia oraz potrzebne ograniczenia.

### Czy należy powtarzać każde błędy?

Nie. Popraw błędy parametrów lub dostępu; ogranicz ponawianie do incydentów tymczasowych i przestrzegaj zasad usługi.