Una API sin resultado y una API con error requieren dos tratamientos diferentes. Una búsqueda exitosa puede no devolver ningún lugar dentro del perímetro consultado. Por el contrario, un error de red, un límite alcanzado o una fuente no disponible impiden concluir a partir de la búsqueda.
Para ROOTE, verifica la respuesta HTTP, luego el estatus de negocio, la colección esperada y la cobertura. Este procedimiento evita mostrar “sin baños” cuando una llamada a Servicios falló o “sin paradas” tras superar el tiempo de espera.
Leer los tres niveles de una respuesta
| Nivel | A controlar | Conclusión posible |
|---|---|---|
| Transporte | Conexión, tiempo de espera y estatus HTTP | ¿La solicitud fue exitosa? |
| Contrato | JSON válido, versión y campos esperados | ¿La respuesta es utilizable? |
| Resultado de negocio | estatus, colecciones, cobertura, advertencias y meta | ¿Qué se sabe dentro del perímetro solicitado? |
Un código HTTP 200 no es suficiente para validar una búsqueda. La respuesta puede indicar ejecución parcial o estatus de error. Por el contrario, un 404 en una ruta no es el medio adecuado para expresar una colección vacía: verifica la URL y el contrato.
Entender success, empty, partial y error
| Estatus | Tratamiento recomendado |
|---|---|
| success | Mostrar las entidades tras validación y conservar los límites |
| empty | Indicar que no se devolvió ningún resultado para esta búsqueda |
| partial | Mostrar la información utilizable con sus advertencias |
| error | Presentar la búsqueda como no disponible; no concluir ausencia de lugares |
La ausencia de resultado se refiere a una solicitud y fuentes conocidas. No prueba que físicamente no exista ningún servicio. Una cobertura no exhaustiva, un filtro restrictivo o un límite aplicado pueden reducir los resultados.
Un árbol de decisión para tu interfaz
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.Verifica los parámetros en el orden correcto
Primero controla latitud y longitud, su orden y la ciudad obtenida. Luego verifica la unidad del radio y el vocabulario de los filtros. La API Services usa types=toilets; una URL de mapa usa modes=toilets. Estos parámetros pertenecen a contratos diferentes.
Luego amplía una dimensión a la vez: aumenta el radio dentro de los límites de la ruta o elimina un filtro para una prueba explícita. Guarda la petición inicial. Si amplías automáticamente, informa el nuevo perímetro al usuario.
Construir una búsqueda API alrededor de coordenadas GPS
Gestionar una fuente no disponible sin perder las demás
Una respuesta parcial puede contener lugares provenientes de fuentes que respondieron mientras otra falló. Conserva esos resultados, sus atribuciones y la advertencia pertinente. No presentes la lista como exhaustiva ni reemplaces campos faltantes con valores predeterminados engañosos.
Una información antigua almacenada en caché también puede ser útil si tu política permite esta alternativa. Debe seguir identificada como antigua. La hora de recepción de tu solicitud no rejuvenece la observación original.
Adaptar mensajes y reintentos
| Situación | Mensaje a adaptar en tu interfaz | Acción |
|---|---|---|
| empty | No se devolvieron resultados en esta zona con estos filtros | Modifica la zona o los filtros |
| partial | Algunos resultados están disponibles; la búsqueda está incompleta | Mostrar resultados y advertencia |
| Error de validación | La búsqueda contiene un parámetro inválido | Corrige la solicitud |
| Autenticación o permisos | Este acceso no permite esta búsqueda | Verifica la cuenta o el token |
| Límite o indisponibilidad | La búsqueda está temporalmente no disponible | Respeta las instrucciones de reintentos |
Para un 429, consulta las instrucciones del servicio y el posible Retry-After. Un error 400 requiere corregir los argumentos; repetir la misma solicitud no lo soluciona. No conviertas un 401 en llamada anónima automática si el usuario proporcionó un token.
Referencia de errores API ROOTE
Prueba los cuatro estados antes de publicar
Prepara respuestas de prueba completas, vacías, parciales y con error, así como un JSON inválido y un tiempo agotado. Verifica el mensaje mostrado, los resultados conservados y el número de reintentos. La prueba esencial es que una falla nunca produzca una afirmación de ausencia de servicios.
Aplicar estas reglas a un asistente IA
Entender los formatos de datos de movilidad
Preguntas frecuentes
¿Una lista vacía prueba ausencia de baños?
No. Solo indica que no se devolvió ningún resultado para esta búsqueda y las fuentes consultadas.
¿Se puede mostrar una respuesta parcial?
Sí, si las entidades usadas son válidas y conservas las advertencias y límites necesarios.
¿Se debe reintentar cada error?
No. Corrige errores de parámetros o acceso; limita reintentos para incidentes transitorios y respeta las instrucciones del servicio.