# Žádný výsledek nebo chyba API: jak to rozeznat?

> Rozlišujte prázdný výsledek, částečnou odpověď a chybu API ROOTE. Zkontrolujte souřadnice, filtry, pokrytí a limity pro správné zobrazení zprávy.

Source: https://www.roote.ai/cs/guides/zadny-vysledek-ci-chyba-api-jak-rozeznat/
Language: cs
Author: ROOTE

API bez výsledku a API s chybou vyžadují odlišný přístup. Úspěšné vyhledávání nemusí vrátit žádné místo v požadovaném rozsahu. Síťová chyba, dosažení limitu nebo nedostupnost zdroje naopak zabraňují závěru ze samotného vyhledávání.

Pro ROOTE zkontrolujte odpověď HTTP, poté stav obchodní logiky, očekávanou kolekci a pokrytí. Tento postup zabrání zobrazování zpráv typu „žádné toalety“, pokud selhal volání služby, nebo „žádná zastávka“ po vypršení časového limitu.

## Čtení tří úrovní odpovědi

| Úroveň | Co zkontrolovat | Možný závěr |
| --- | --- | --- |
| Přenos | Připojení, časový limit a HTTP stav | Dokončil se požadavek úspěšně? |
| Smlouva | Platný JSON, verze a očekávaná pole | Je odpověď využitelná? |
| Výsledek obchodní logiky | status, kolekce, pokrytí, varování a meta | Co víme v požadovaném rozsahu? |

HTTP kód 200 nestačí k potvrzení vyhledávání. Odpověď může signalizovat částečný průběh nebo stav error. Naopak, 404 na cestě není běžný způsob vyjádření prázdné kolekce: zkontrolujte URL a smlouvu.

## Pochopení statusů success, empty, partial a error

| Stav | Doporučené zpracování |
| --- | --- |
| success | Zobrazit entity po ověření a zachovat limity |
| empty | Upozornit, že vyhledávání nevrátilo žádný výsledek |
| partial | Zobrazit použitelné informace s příslušnými varováními |
| error | Prezentovat vyhledávání jako nedostupné; nezávěrujte absenci míst |

Absence výsledku se vztahuje k dotazu a známým zdrojům. Neznamená fyzickou neexistenci služeb. Neúplné pokrytí, restriktivní filtr nebo aplikovaný limit mohou snížit počet výsledků.

## Rozhodovací strom pro vaše rozhraní

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

## Kontrola parametrů ve správném pořadí

Nejdříve zkontrolujte zeměpisnou šířku a délku, jejich pořadí a získané město. Poté ověřte jednotku poloměru a slovník filtrů. API Služby používá types=toilets; URL mapy používá modes=toilets. Tyto parametry patří do různých smluv.

Postupně rozšiřte jen jeden rozměr: zvětšete poloměr v mezích cesty nebo odstraňte filtr pro jasný test. Uchovejte původní dotaz. Pokud automaticky rozšiřujete, informujte uživatele o novém rozsahu.

[Vytvoření API vyhledávání kolem GPS souřadnic](https://www.roote.ai/cs/guides/jak-vyhledat-dopravni-zastavky-blizko-se-pomoci-api/)

## Zpracování nedostupného zdroje bez ztráty ostatních

Částečná odpověď může obsahovat místa ze zdrojů, které odpověděly, zatímco jiné selhaly. Zachovejte tyto výsledky, jejich atributy a odpovídající varování. Neprezentujte seznam jako úplný a nenahrazujte chybějící pole klamavými výchozími hodnotami.

I stará informace v cache může být užitečná, jestliže vaše politika tento fallback povoluje. Musí ale být označena jako zastaralá. Čas přijetí vašeho požadavku nevykresluje pozorování na novější.

## Přizpůsobení zpráv a obnovy

| Situace | Zpráva přizpůsobená vašemu rozhraní | Akce |
| --- | --- | --- |
| empty | V této oblasti s danými filtry nebyl vrácen žádný výsledek | Změnit oblast nebo filtry |
| partial | Některé výsledky jsou dostupné; vyhledávání je neúplné | Zobrazit výsledky a varování |
| Chyba validace | Vyhledávání obsahuje neplatný parametr | Opravit dotaz |
| Autentizace nebo oprávnění | Tento přístup neumožňuje toto vyhledávání | Zkontrolovat účet nebo token |
| Limit nebo nedostupnost | Vyhledávání je dočasně nedostupné | Dodržovat pokyny pro opakování |

Pro 429 dodržujte pokyny služby a případné Retry-After. Chyba 400 vyžaduje opravu argumentů; opakování stejného dotazu ji nevyřeší. Neprovádějte anonymní volání při 401, pokud uživatel poskytl token.

[Referenční chybové kódy API ROOTE](https://doc.roote.ai/roote-api/errors)

[Stav služeb ROOTE](https://status.roote.ai/)

## Testujte všechny čtyři stavy před zveřejněním

Připravte kompletní testovací odpovědi: plné, prázdné, částečné a chybové, také neplatný JSON a překročení limitu. Zkontrolujte zobrazenou zprávu, zachované výsledky a počet opakování. Hlavním testem je, aby výpadek nikdy nezpůsobil tvrzení o absenci služeb.

[Aplikace těchto pravidel na AI asistenta](https://www.roote.ai/cs/guides/jak-vytvorit-asistenta-ktory-najde-mobilitu-okolo-adresy/)

[Pochopení formátů dat mobility](https://www.roote.ai/cs/guides/gtfs-gtfs-rt-a-gbfs-jake-rozdily/)

## Často kladené otázky

### Dokazuje prázdný seznam absenci toalet?

Ne. Pouze znamená, že pro toto vyhledávání a zdroje nebyl vrácen žádný výsledek.

### Lze zobrazit částečnou odpověď?

Ano, pokud jsou použité entity platné a zachováte příslušná varování a limity.

### Je třeba opakovat každou chybu?

Ne. Opravte chyby v parametrech nebo přístupu; omezte opakování pouze na přechodné problémy a dodržujte pokyny služby.