An API with no result and an API with an error require two different treatments. A successful search may return no locations within the requested area. Conversely, a network error, a reached limit, or an unavailable source prevents concluding from the search.
For ROOTE, check the HTTP response first, then the business status, the expected collection, and the coverage. This approach avoids displaying 'no toilets' when a Services call has failed or 'no stops' after a timeout.
Reading the three levels of a response
| Level | To check | Possible conclusion |
|---|---|---|
| Transport | Connection, timeout, and HTTP status | Did the request succeed? |
| Contract | Valid JSON, version, and expected fields | Is the response usable? |
| Business result | status, collections, coverage, warnings, and meta | What is known within the requested scope? |
An HTTP 200 code is not enough to validate a search. The response may indicate partial execution or an error status. Conversely, a 404 on a route is not a normal way to express an empty collection: verify the URL and the contract.
Understanding success, empty, partial, and error
| Status | Recommended handling |
|---|---|
| success | Display entities after validation and keep limits |
| empty | Indicate that no results were returned for this search |
| partial | Display the usable information with their warnings |
| error | Present the search as unavailable; do not conclude the absence of locations |
No result applies to a request and known sources. It does not prove that no service exists physically. Non-exhaustive coverage, restrictive filters, or an applied limit can reduce results.
A decision tree for your interface
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.Check parameters in the correct order
First verify latitude and longitude, their order, and the city obtained. Then check the radius unit and filter vocabulary. The Services API uses types=toilets; a map URL uses modes=toilets. These parameters belong to different contracts.
Then expand one dimension at a time: increase the radius within route limits or remove a filter for an explicit test. Keep track of the initial request. If you expand automatically, inform the user of the new scope.
Building an API search around GPS coordinates
Handling an unavailable source without losing others
A partial response may contain places from sources that replied while another failed. Keep these results, their attributions, and the relevant warning. Do not present the list as exhaustive and do not replace missing fields with misleading default values.
An old cached information can also be useful if your policy allows fallback. It must remain identified as old. The reception time of your request does not refresh the original observation.
Adapting messages and retries
| Situation | Message to adapt to your interface | Action |
|---|---|---|
| empty | No results returned in this area with these filters | Change the area or filters |
| partial | Some results are available; the search is incomplete | Display results and warning |
| Validation error | The search contains an invalid parameter | Correct the request |
| Authentication or rights | This access does not allow this search | Check the account or token |
| Limit or unavailability | The search is temporarily unavailable | Respect retry guidelines |
For a 429, check the service guidelines and possible Retry-After. A 400 error requires argument correction; repeating the same request does not fix it. Do not turn a 401 into an automatic anonymous call if the user provided a token.
Reference for ROOTE API errors
Test the four states before publishing
Prepare complete, empty, partial, and error test responses, as well as invalid JSON and timeout. Check the displayed message, retained results, and number of retries. The essential test is that a failure never produces a claim of no services.
Apply these rules to an AI assistant
Understanding mobility data formats
Frequently asked questions
Does an empty list prove the absence of toilets?
No. It only indicates that no results were returned for this search and the consulted sources.
Can a partial response be displayed?
Yes, if the used entities are valid and if you keep the necessary warnings and limits.
Should every error be retried?
No. Correct parameter or access errors; limit retries for transient incidents and respect the service guidelines.