Write the states before drawing the spinner
This is a proposed flow for a developer-owned hiking app, not a record of observed API behavior. The walker enters offline maps, requests historical discussion and waits. The app needs to distinguish an untouched form, an unresolved request, returned records, a successful empty response and a failure. One blank panel cannot communicate those different situations.
Begin with a neutral idle screen that explains what will be searched. Typing alone need not make a request. On explicit submission, store the submitted question with that request and show a loading label. Keep the input readable and prevent repeated taps from sending the same action several times. A spinner is feedback about waiting, not evidence of progress through the archive.
Keep a late response attached to its question
Imagine the walker changes the input to downloaded regions while the offline-maps request is still pending. This is an illustrative interaction, not a retrieved search example. Your app must decide whether to wait, start another request or let the person cancel the view. Whichever choice you implement, the earlier response must not silently become the answer to the new phrase.
Associate each request with its submitted input in your own application state. On arrival, check whether that response still belongs in the current view. Discarding a late response from the screen is not the same as canceling the server’s work: a request already sent might finish successfully and be charged. Test that distinction in your own implementation.
Treat successful empty as a result
For returned records, show the fields you actually have and retain the historical-source label. For an empty data array, use a separate message explaining that this request returned no records. Offer editing the phrase or filters, while preserving them so the reader can make an informed change. Do not replace an empty result with invented popular posts.
Successful empty retrievals cost one credit, just like successful responses with records. That is a reason to make query changes intentional rather than to hide empty responses as errors. Avoid a message claiming that no relevant discussion exists anywhere; the archive is incomplete, and the response has a particular query and bounded window.
Give the operator the technical problem
A 400 response calls for checking request input. If the app supplied an invalid date or unsupported parameter, do not blame the walker for a backend contract mistake. A 401 indicates a missing or invalid service key; reloading the app or asking the walker to sign in does not necessarily repair that credential.
A 402 indicates insufficient service-account credits. Route that decision to the operator instead of displaying an invoice to the walker. A 429 calls for respecting Retry-After and reducing repeated requests. Because the app may share an account across readers, avoid automatically telling one person they caused the limit.
Separate a known failure from an unknown outcome
The gateway returns 502 when an upstream retrieval fails. Its reserved credit is released or reported as pending reconciliation. Preserve the query and any earlier visible page, then offer a bounded retry choice. Repeated automatic retries can create more requests without helping the reader understand what happened.
If your app never receives a response, it may not know whether the server failed or completed. Record that uncertainty for reconciliation; do not display a definite refund or success claim. The public /v1/status route is a static scope/HTTP-response check, so it cannot settle that question or certify that archive search is healthy.
Review the transitions, not only the screenshots
Walk through the proposed sequence with the person who owns the app: submit, edit while waiting, receive empty, retry after failure, load another page and leave the screen. For each transition, name the retained input, visible content and next action. An attractive mock screen does not prove that those transitions work.
Keep operator diagnostics, raw service responses and credentials away from public-facing messages. Give the walker enough context to continue trip preparation without relying on an unavailable discussion feature. Return to /en/#field-notes for the request-budget and Show more decisions that shape this state flow.
