A search screen needs more than results or error

A storyboard, not a service-status display

These are proposed states for a developer-owned hiking app. They are not captured API responses, working screen demonstrations or evidence that any offline-maps record is available. The walker uses your app; the API account operator manages the service credential and credits. Give each person the information they can act on.

Before the first search, explain that the feature reads historical discussions. A suggested query such as offline maps can help someone start, but do not show invented recommendations as if a search has already run. Keep an explicit Search action so typing and browsing the form need not trigger a paid request.

Loading: keep the question visible

While a request is pending, retain the submitted query and selected filters. Mark the result area as loading, prevent duplicate submissions for that action, and offer an accessible text label alongside any animation. A delay alone does not identify a service outage or its cause.

If the person changes the query before an earlier response arrives, associate each response with its submitted input. Do not silently place results for the old question under the new one. This is an app implementation choice to test, not ordering or cancellation behavior supplied by the archive API.

Success can contain records or nothing

With returned records, show only available fields and identify the material as historical. A comment need not have a title, and a missing date should remain unknown. Describe the visible page rather than announcing an exact match count when pagination.relation is gte or unknown.

A successful empty response is a distinct outcome. A possible message is: No records were returned for this request. Offer a deliberate change to the wording or filters, keeping the existing input available. Do not claim that no such discussion exists anywhere. A successful empty retrieval still costs one credit.

400, 401 and 402 need different owners

HTTP 400 indicates invalid request input. Check the actual parameter problem: an unsupported parameter, an out-of-range page or a date outside the YYYY-MM-DD format are examples. Explain a correctable field to the walker when applicable, and keep backend contract errors in operator diagnostics.

HTTP 401 means a missing or invalid service API key. It does not establish that the walker’s app session expired, and these API keys do not have a documented timed-expiry mechanism. The operator checks the saved domain-specific key and any recent regeneration. Do not ask the walker to supply a key or sign in to the service account.

HTTP 402 means insufficient service-account credits. A walker-facing message might say Discussion search is temporarily paused. The operator can sign in on Key and credits and review the balance. A new request is a separate action after the cause has been addressed; simply repeating the old request is not a remedy.

429, upstream failure and uncertain delivery

HTTP 429 means a rate limit was reached. Respect Retry-After, reduce repeated submissions and let the person try again when appropriate. The limit may involve a shared backend or account, so avoid blaming an individual walker. Do not spin in an unlimited automatic retry loop.

The gateway reports upstream failures as HTTP 502. Preserve the query and show an explicit retry option without promising that the next attempt will succeed. Reserved credit is refunded on a failed upstream request; the response can also report pending reconciliation. If your app loses the response entirely, the final billing outcome is uncertain: the server might have completed successfully.

The public /v1/status route supplies a static service-scope disclosure and shows that its HTTP handler responds. It does not test archive search or certify upstream health. Build operational decisions from the actual request outcome. Return to App walkthrough for the full storyboard or Loading, empty and error screens in Field notes for implementation choices.