# Ei tulosta tai API-virhe: kuinka tehdä ero?

> Erota tyhjä tulos, osittainen vastaus ja ROOTE API-virhe. Tarkista koordinaatit, suodattimet, kattavuus ja rajat oikean viestin näyttämiseksi.

Source: https://www.roote.ai/fi/guides/ei-tulosta-tai-api-virhe-kuinka-eroittaa/
Language: fi
Author: ROOTE

Tulokseton API-vastaus ja virhetilanne vaativat eri käsittelytapoja. Onnistunut haku voi palauttaa hakualueelta nolla sijaintia. Verkko-ongelma, rajan ylitys tai lähteen poissaolo estää johtopäätöksen tekemisen haun perusteella.

ROOTE: tarkista ensin HTTP-vastaus, sitten liiketoimintastatus, odotettu kokoelma ja kattavuus. Tämä estää näyttämästä ’ei wc-tiloja’ kun Services-kutsu epäonnistui tai ’ei pysäkkejä’ odotusajan ylityksen jälkeen.

## Vastauksen kolmen tason lukeminen

| Taso | Tarkistettava | Mahdollinen johtopäätös |
| --- | --- | --- |
| Kuljetus | Yhteys, aikakatkaisu ja HTTP-tila | Onko pyyntö onnistunut? |
| Sopimus | Kelvollinen JSON, versio ja odotetut kentät | Onko vastaus hyödynnettävissä? |
| Liiketoimintatulos | status, kokoelmat, kattavuus, varoitukset ja meta | Mitä tiedetään pyydetyllä alueella? |

HTTP 200 ei riitä vahvistamaan hakua. Vastaus voi ilmoittaa osasuorituksen tai virhetilan. Toisaalta reitin 404 ei ole normaali tapa ilmaista tyhjää kokoelmaa: tarkista URL ja sopimus.

## Menestys, tyhjä, osittainen ja virhe: ymmärtäminen

| Tila | Suositeltu käsittely |
| --- | --- |
| success | Näytä kohteet validoinnin jälkeen ja säilytä rajat |
| empty | Ilmoita, ettei hakutuloksia löytynyt |
| partial | Näytä hyödynnettävät tiedot varoitukset säilyttäen |
| error | Ilmoita haku poissa käytöstä; älä tee johtopäätöstä kohteiden puuttumisesta |

Tulokseton haku koskee tunnettua pyyntöä ja lähteitä. Se ei todista palvelujen existencia fyysisesti. Rajoittamaton kattavuus, tiukka suodin tai sovellettu raja voivat vähentää tuloksia.

## Päätöspuu käyttöliittymällesi

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

## Tarkista parametrit oikeassa järjestyksessä

Tarkista ensin leveys- ja pituusaste, niiden järjestys ja saadun kaupungin nimi. Tarkista sitten säteen yksikkö ja suodattimien sanasto. Services API käyttää types=toilets; kartta-URL modes=toilets. Nämä parametrit kuuluvat eri sopimuksiin.

Laajenna sitten yhtä mittaa kerrallaan: suurennna säteen rajoissa tai poista suodin eksplisiittiseen testiin. Säilytä alkuperäinen pyyntö. Ilmoita käyttäjälle automaattisesta laajennuksesta uusi hakualue.

[Rakenna API-haku GPS-koordinaattien ympärille](https://www.roote.ai/fi/guides/kuinka-etsi%C3%A4-l%C3%A4hell%C3%A4-olevia-liikennepys%C3%A4kkej%C3%A4-api-rajapinnan-avulla/)

## Käsittele poissa oleva lähde menettämättä muita

Osittainen vastaus voi sisältää sijainteja vastanneista lähteistä, vaikka joku toinen epäonnistui. Säilytä nämä tulokset, niiden lähdeviittaukset ja asiaankuuluva varoitus. Älä esitä listaa täydellisenä äläkä korvaa puuttuvia kenttiä harhaanjohtavilla oletusarvoilla.

Välimuistissa oleva vanha tieto voi myös olla hyödyllinen, jos käytäntösi sallii tämän varavaihtoehdon. Sen tulee pysyä merkittynä vanhaksi. Pyynnön vastaanottoaika ei nuorennä alkuperäistä havaintoa.

## Sovitettavat viestit ja toipumiskeinot

| Tilanne | Mukautettava viesti käyttöliittymällesi | Toimenpide |
| --- | --- | --- |
| empty | Tällä alueella ja suodattimilla ei löytynyt tuloksia | Muuta aluetta tai suodattimia |
| partial | Osa tuloksista saatavilla; haku on puutteellinen | Näytä tulokset ja varoitus |
| Validointivirhe | Haku sisältää virheellisen parametrin | Korjaa pyyntö |
| Todennus tai oikeudet | Tällä pääsyllä ei saa tehdä tätä hakua | Tarkista tili tai tunniste |
| Rajoitus tai poissaolo | Haku on tilapäisesti poissa käytöstä | Noudata uudelleenyritysohjeita |

429-tilanteessa noudata palvelun ohjeita ja mahdollisesti Retry-After-arvoa. Virhe 400 vaatii argumenttien korjauksen; saman pyynnön toistaminen ei ratkaise. Älä muuta 401:stä anonyymiksi automaattiksi kutsuksi, jos käyttäjä antoi tunnisteen.

[ROOTE API-virheiden viitetiedot](https://doc.roote.ai/roote-api/errors)

[ROOTE-palvelujen tila](https://status.roote.ai/)

## Testaa neljä tilaa ennen julkaisua

Valmistele täydelliset, tyhjät, osittaiset ja virhevastaukset sekä virheellinen JSON ja aikakatkaisu. Tarkista näytetty viesti, säilytetyt tulokset ja uudelleenyritysten määrä. Keskeistä on, ettei vika koskaan vahvista palvelujen puuttumista.

[Sovella näitä sääntöjä tekoälyavustimeen](https://www.roote.ai/fi/guides/kuinka-luoda-liikkumisavustaja-osoitteen-ymparille/)

[Ymmärrä liikkumisen tietomuodot](https://www.roote.ai/fi/guides/gtfs-gtfsrt-ja-gbfs-mika-erot/)

## Usein kysytyt kysymykset

### Todistaako tyhjä lista wc-tilojen puuttumisen?

Ei. Se vain kertoo, ettei haussa ja lähteissä löytynyt tuloksia.

### Voiko näyttää osittaisen vastauksen?

Kyllä, jos käytetyt kohteet ovat kelvollisia ja varoitukset sekä rajat säilytetään.

### Pitäisikö uudelleen yrittää joka virhe?

Ei. Korjaa parametri- tai käyttöoikeusvirheet; rajoita uudelleenyritykset väliaikaisiin häiriöihin ja noudata palvelun ohjeita.