# Fără rezultate sau eroare API: cum să faci diferența?

> Diferențiază rezultat gol, răspuns parțial și eroare API ROOTE. Verifică coordonate, filtre, acoperire și limite pentru a afișa mesajul corect.

Source: https://www.roote.ai/ro/guides/fara-rezultate-sau-eroare-api-cum-sa-faci-diferenta/
Language: ro
Author: ROOTE

O API fără rezultat și o API cu eroare necesită două tratamente diferite. O căutare reușită poate să nu returneze niciun loc în perimetrul consultat. O eroare de rețea, o limită atinsă sau o sursă indisponibilă împiedică, dimpotrivă, concluzionarea pe baza căutării.

Pentru ROOTE, verifică răspunsul HTTP apoi statutul de business, colecția așteptată și acoperirea. Această procedură evită afișarea „nici o toaletă” când un apel Services a eșuat sau „niciun staționament” după un timp de așteptare depășit.

## Citirea celor trei nivele ale unui răspuns

| Nivel | De verificat | Concluzie posibilă |
| --- | --- | --- |
| Transport | Conexiune, timp de răspuns și status HTTP | Cererea a fost finalizată? |
| Contract | JSON valid, versiune și câmpuri așteptate | Răspunsul este exploatabil? |
| Rezultat de business | status, colecții, acoperire, avertismente și meta | Ce se cunoaște în perimetrul cerut? |

Un cod HTTP 200 nu este suficient pentru validarea unei căutări. Răspunsul poate indica o execuție parțială sau un status error. În schimb, un 404 pe o rută nu este o metodă normală de a exprima o colecție goală: verifică URL-ul și contractul.

## Înțelegerea statusurilor success, empty, partial și error

| Status | Tratament recomandat |
| --- | --- |
| success | Afișează entitățile după validare și păstrează limitele |
| empty | Indică faptul că nu a fost returnat niciun rezultat pentru această căutare |
| partial | Arată informațiile utilizabile împreună cu avertismentele lor |
| error | Prezintă căutarea ca indisponibilă; nu concluziona că nu există locuri |

Lipsa rezultatului se referă la o cerere și surse cunoscute. Ea nu dovedește că nu există servicii fizice. O acoperire incompletă, un filtru restrictiv sau o limită aplicată pot reduce rezultatele.

## Un arbore decizional pentru interfața ta

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

## Verifică parametrii în ordinea corectă

Verifică mai întâi latitudinea și longitudinea, ordinea lor și orașul obținut. Verifică apoi unitatea razei și vocabularul filtrelor. API-ul Services folosește types=toilets; o URL de hartă folosește modes=toilets. Acești parametri aparțin unor contracte diferite.

Extinde apoi o singură dimensiune pe rând: mărește raza în limitele traseului sau elimină un filtru pentru un test explicit. Păstrează istoricul cererii inițiale. Dacă extinzi automat, informează utilizatorul despre noul perimetru.

[Construirea unei căutări API în jurul coordonatelor GPS](https://www.roote.ai/ro/guides/cum-sa-cauti-statiile-de-transport-apropiate-cu-o-api/)

## Gestionarea unei surse indisponibile fără a pierde celelalte

Un răspuns parțial poate conține locuri provenite din surse care au răspuns, în timp ce una a eșuat. Păstrează aceste rezultate, atribuțiile lor și avertismentul relevant. Nu prezenta lista ca fiind exhaustivă și nu înlocui câmpurile lipsă cu valori implicite înșelătoare.

O informație veche păstrată în cache poate fi de asemenea utilă dacă politica ta permite această măsură de rezervă. Ea trebuie să rămână identificată ca veche. Ora primirii cererii tale nu reînnoiește observația inițială.

## Adaptarea mesajelor și a reluărilor

| Situație | Mesaj de adaptat interfeței tale | Acțiune |
| --- | --- | --- |
| empty | Niciun rezultat returnat în această zonă cu aceste filtre | Modifică zona sau filtrele |
| partial | Unele rezultate sunt disponibile; căutarea este incompletă | Afișează rezultatele și avertismentul |
| Eroare de validare | Căutarea conține un parametru invalid | Corectează cererea |
| Autentificare sau drepturi | Accesul acesta nu permite această căutare | Verifică contul sau token-ul |
| Limită sau indisponibilitate | Căutarea este temporar indisponibilă | Respectă instrucțiunile de reluare |

Pentru un 429, consultă instrucțiunile serviciului și eventual Retry-After. O eroare 400 solicită corectarea argumentelor; repetarea aceleiași cereri nu o rezolvă. Nu transforma un 401 în apel anonim automat dacă utilizatorul a furnizat un token.

[Referință erori API ROOTE](https://doc.roote.ai/roote-api/errors)

[Starea serviciilor ROOTE](https://status.roote.ai/)

## Testează cele patru stări înainte de publicare

Pregătește răspunsuri de test complete, goale, parțiale și cu eroare, precum și JSON invalid și timeout. Verifică mesajul afișat, rezultatele păstrate și numărul de reluări. Testul esențial este ca o defecțiune să nu genereze niciodată afirmația de lipsă a serviciilor.

[Aplicarea acestor reguli într-un asistent IA](https://www.roote.ai/ro/guides/cum-sa-creezi-un-asistent-pentru-mobilitati-in-jurul-unei-adrese/)

[Înțelegerea formatelor de date de mobilitate](https://www.roote.ai/ro/guides/gtfs-gtfs-rt-si-gbfs-ce-diferente/)

## Întrebări frecvente

### Dovedește o listă goală lipsa toaletei?

Nu. Indică doar că nu a fost returnat niciun rezultat pentru această căutare și sursele consultate.

### Se poate afișa un răspuns parțial?

Da, dacă entitățile utilizate sunt valide și dacă păstrezi avertismentele și limitele necesare.

### Trebuie relansată fiecare eroare?

Nu. Corectează erorile de parametri sau acces; limitează reluările pentru incidente tranzitorii și respectă instrucțiunile serviciului.