Una pantalla de búsqueda necesita algo más que resultados o error

Un guion de pantallas, no un indicador del estado del servicio

Estos son estados propuestos para una app de senderismo desarrollada por ti. No son respuestas capturadas de la API, demostraciones de pantallas en funcionamiento ni pruebas de que haya registros sobre offline maps. La persona usa tu app; el operador de la cuenta API administra la credencial del servicio y los créditos. Dale a cada uno la información sobre la que puede actuar.

Antes de la primera búsqueda, explica que la función consulta conversaciones históricas. Una consulta sugerida como offline maps puede ayudar a empezar, pero no muestres recomendaciones inventadas como si ya se hubiera ejecutado una búsqueda. Mantén una acción Buscar explícita para que escribir y explorar el formulario no tenga que generar una solicitud de pago.

Carga: conserva visible la pregunta

Mientras una solicitud esté pendiente, conserva la consulta enviada y los filtros seleccionados. Marca la zona de resultados como cargando, evita envíos duplicados para esa acción y acompaña cualquier animación con una etiqueta de texto accesible. Un retraso por sí solo no identifica una caída del servicio ni su causa.

Si la persona cambia la consulta antes de que llegue una respuesta anterior, vincula cada respuesta con la entrada que se envió. No coloques silenciosamente resultados de la pregunta anterior bajo la nueva. Es una decisión de implementación que debes probar en tu app, no un comportamiento de ordenación o cancelación que suministre la API del archivo.

Una respuesta correcta puede tener registros o estar vacía

Si se devuelven registros, muestra solo los campos disponibles e identifica el material como histórico. Un comentario no tiene por qué incluir título y una fecha ausente debe seguir siendo desconocida. Describe la página visible en lugar de anunciar una cantidad exacta de coincidencias cuando pagination.relation sea gte o unknown.

Una respuesta vacía correcta es un resultado distinto. Un mensaje posible es: Esta solicitud no devolvió registros. Ofrece un cambio deliberado de las palabras o los filtros y conserva la entrada existente. No afirmes que esa conversación no existe en ningún lugar. Una recuperación vacía correcta sigue costando un crédito.

400, 401 y 402 requieren responsables distintos

HTTP 400 indica una entrada de solicitud inválida. Comprueba el problema concreto del parámetro: por ejemplo, uno no admitido, una página fuera de rango o una fecha que no cumple YYYY-MM-DD. Cuando corresponda, explica a la persona qué campo puede corregir y deja los errores del contrato del backend en los diagnósticos del operador.

HTTP 401 significa que falta la clave API del servicio o no es válida. No demuestra que la sesión de la persona en la app haya caducado, y no hay un mecanismo documentado de caducidad programada para estas claves API. El operador comprueba la clave guardada para este dominio y cualquier regeneración reciente. No pidas a quien camina que proporcione una clave o inicie sesión en la cuenta del servicio.

HTTP 402 significa que la cuenta del servicio no tiene créditos suficientes. Un mensaje para la app podría indicar que la búsqueda de conversaciones está temporalmente en pausa. El operador puede entrar en Clave y créditos y revisar el saldo. Una nueva solicitud es una acción distinta una vez resuelta la causa; repetir la anterior sin más no es una solución.

429, fallo de la fuente y entrega incierta

HTTP 429 significa que se ha alcanzado un límite de solicitudes. Respeta Retry-After, reduce los envíos repetidos y permite intentarlo de nuevo cuando corresponda. El límite puede afectar a un backend o una cuenta compartidos, así que evita culpar a una sola persona. No entres en un bucle automático de reintentos sin límite.

El gateway comunica los fallos de la fuente ascendente como HTTP 502. Conserva la consulta y muestra una opción explícita para reintentar, sin prometer que el siguiente intento tendrá éxito. Si falla una solicitud a esa fuente, el crédito reservado se reintegra; la respuesta también puede indicar una conciliación pendiente. Si tu app pierde la respuesta por completo, la facturación final es incierta: el servidor podría haber terminado correctamente.

La ruta pública /v1/status proporciona una declaración estática del alcance del servicio y muestra que responde su controlador HTTP. No prueba búsquedas en el archivo ni certifica el estado de la fuente ascendente. Basa las decisiones operativas en el resultado real de la solicitud. Vuelve al Recorrido de la app para ver el guion completo o a la nota sobre carga, vacío y error para las decisiones de implementación.