# Nessun risultato o errore API: come fare la differenza?

> Differenzia risultato vuoto, risposta parziale ed errore API ROOTE. Controlla coordinate, filtri, copertura e limiti per mostrare il messaggio corretto.

Source: https://www.roote.ai/it/guides/nessun-risultato-o-errore-api-come-fare-la-differenza/
Language: it
Author: ROOTE

Un'API senza risultati e un'API in errore richiedono due trattamenti diversi. Una ricerca riuscita può non restituire alcun luogo nell'area consultata. Un errore di rete, un limite raggiunto o una fonte non disponibile impediscono invece di trarre conclusioni dalla ricerca.

Per ROOTE, controlla la risposta HTTP poi lo stato business, la collezione attesa e la copertura. Questo evita di mostrare «nessun bagno» quando una chiamata ai Servizi è fallita o «nessuna fermata» dopo un timeout.

## Leggere i tre livelli di una risposta

| Livello | Da controllare | Conclusione possibile |
| --- | --- | --- |
| Trasporto | Connessione, timeout e stato HTTP | La richiesta è andata a buon fine? |
| Contratto | JSON valido, versione e campi attesi | La risposta è sfruttabile? |
| Risultato business | status, collezioni, copertura, avvisi e meta | Cosa si sa nell'area richiesta? |

Un codice HTTP 200 non basta a convalidare una ricerca. La risposta può indicare esecuzione parziale o stato error. Viceversa, un 404 su una rotta non è modo normale di esprimere una collezione vuota: verifica l’URL e il contratto.

## Comprendere success, empty, partial ed error

| Stato | Trattamento consigliato |
| --- | --- |
| success | Mostrare le entità dopo validazione e mantenere i limiti |
| empty | Indicare che non è stato restituito alcun risultato per questa ricerca |
| partial | Mostrare le informazioni utilizzabili con i loro avvisi |
| error | Presentare la ricerca come non disponibile; non concludere assenza di luoghi |

L’assenza di risultati riguarda una richiesta e fonti note. Non prova che nessun servizio esista fisicamente. Copertura non esaustiva, filtro restrittivo o limite applicato possono ridurre i risultati.

## Un albero decisionale per la tua interfaccia

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

## Verificare i parametri nel giusto ordine

Controlla prima latitudine e longitudine, il loro ordine e la città ottenuta. Poi verifica l’unità di raggio e il vocabolario dei filtri. L’API Servizi usa types=toilets; un URL di mappa usa modes=toilets. Questi parametri appartengono a contratti diversi.

Estendi poi una sola dimensione alla volta: aumenta il raggio entro limiti della rotta o rimuovi un filtro per un test esplicito. Tieni traccia della richiesta iniziale. Se allarghi automaticamente, informa l’utente del nuovo perimetro.

[Costruire una ricerca API attorno a coordinate GPS](https://www.roote.ai/it/guides/come-ricercare-le-fermate-di-trasporto-vicino-con-una-api/)

## Gestire una fonte non disponibile senza perdere le altre

Una risposta parziale può contenere luoghi da fonti che hanno risposto mentre un’altra è fallita. Conserva questi risultati, le loro attribuzioni e l’avviso pertinente. Non presentare la lista come esaustiva e non sostituire campi mancanti con valori default fuorvianti.

Una informazione vecchia memorizzata in cache può essere utile se la tua politica lo permette. Deve però restare identificata come datata. L’ora della tua richiesta non rinfresca l’osservazione originale.

## Adattare i messaggi e le azioni di ripresa

| Situazione | Messaggio da adattare alla tua interfaccia | Azione |
| --- | --- | --- |
| empty | Nessun risultato restituito in questa zona con questi filtri | Modifica la zona o i filtri |
| partial | Alcuni risultati sono disponibili; la ricerca è incompleta | Mostra risultati e avviso |
| Errore di validazione | La ricerca contiene un parametro non valido | Correggi la richiesta |
| Autenticazione o diritti | Questo accesso non permette questa ricerca | Verifica l’account o il token |
| Limite o indisponibilità | La ricerca è temporaneamente non disponibile | Rispetta le indicazioni di ripresa |

Per un 429, consulta le indicazioni del servizio e l’eventuale Retry-After. Un errore 400 richiede correzione degli argomenti; ripetere la stessa richiesta non risolve. Non trasformare un 401 in chiamata anonima automatica se l’utente ha fornito un token.

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

[Stato dei servizi ROOTE](https://status.roote.ai/)

## Testare i quattro stati prima di pubblicare

Prepara risposte di test complete, vuote, parziali e in errore, un JSON invalido e timeout. Verifica messaggi mostrati, risultati mantenuti e numero di riprese. Il test essenziale è che un guasto non produca mai l’affermazione di assenza di servizi.

[Applicare queste regole a un assistente IA](https://www.roote.ai/it/guides/come-creare-un-assistente-che-trova-le-mobilita-intorno-a-un-indirizzo/)

[Comprendere i formati dati della mobilità](https://www.roote.ai/it/guides/gtfs-gtfs-rt-e-gbfs-quali-differenze/)

## Domande frequenti

### Una lista vuota prova l’assenza di bagni?

No. Indica solo che non è stato restituito alcun risultato per questa ricerca e le fonti consultate.

### Si può mostrare una risposta parziale?

Sì, se le entità usate sono valide e se conservi gli avvisi e i limiti necessari.

### Bisogna rilanciare ogni errore?

No. Correggi errori di parametri o accesso; limita i tentativi per incidenti transitori e rispetta le indicazioni del servizio.