All posts

Tools

Make your demo survive a failed API request

Design loading, timeout and retry behavior around the operation so a temporary service problem does not erase the user’s work.

HackHoster Team · · 4 min read

Smoked glass channels joining through a copper connector and charcoal ring
Illustration: HackHoster (AI-assisted), original artwork

At a glance

  • Distinguish transport failures from unsuccessful service responses.
  • Preserve input and explain what the user can try next.
  • Retry only when the operation can be repeated safely.
  • Label recorded examples and offline modes as demonstrations.

Practical guidance from HackHoster. Sources and illustration credits accompany the article. Publishing standards and corrections.

A live demo becomes easier to trust when a failed request has an understandable outcome. Preserve the user's input, explain the current state and offer a safe next action. You cannot promise that an external service will be available during judging, but you can decide how your application behaves when it is not.

Start with the operation rather than a generic retry button. Loading a public list, generating a paid response and sending an email have different consequences if repeated. The suggestions below are a planning and testing method. Follow the relevant provider documentation for status codes, limits and duplicate-request protection.

Conceptual illustration of separate components connected into a reliable path
Illustration: HackHoster (AI-assisted), original artwork

Name the states before writing the interface

List the states that affect the user's task: ready, working, complete, failed and possibly uncertain. Uncertain matters when the application does not know whether a request finished. For example, a timeout after sending a message does not automatically prove that the message was never delivered.

Write a short sentence for each state. The text should explain what happened and what the person can do. Avoid a spinner that can continue forever without explanation. For a small prototype, a clear status with preserved input can be more useful than a sophisticated progress bar that does not represent actual progress.

Distinguish a failed connection from a failed result

A request can reach a service and still receive an unsuccessful status. A browser can also fail to connect at all. If you use Fetch, MDN explains why checking the response status is separate from handling a rejected request. Test both paths rather than assuming one error handler describes every failure correctly.

Your application should also inspect the expected response shape before using it. A successful transport does not guarantee that the body contains a valid result for your workflow. Keep unexpected responses out of the main display and provide a safe explanation. Do not expose raw service output if it contains internal details or credentials.

Preserve the work the person already did

Keep the submitted text or selected file context available after failure when practical. Let the person correct an input without starting from an empty screen. If a draft was saved, identify which version is stored. Confusion about whether work survived can be more frustrating than the original temporary outage.

Consider a document summarizer. If processing fails, show the document name, retain the chosen settings and offer another attempt when appropriate. Do not imply that a summary was saved when it was not. If you store content on the server, explain the behavior accurately and avoid retaining more material merely to simplify the demo.

Retry is a product decision. Before offering it, decide what could happen if the original operation actually completed.

Keep repeated operations safe

A read-only request may be straightforward to repeat, while a payment, message or record creation can have side effects. Use the provider's supported duplicate-protection mechanism when the operation requires it. A disabled button helps prevent accidental double clicks, but it does not replace server-side protection against repeated requests.

Decide how long the interface will wait and what it should say afterward. Avoid rapid automatic loops that increase cost or load without helping the user. A bounded attempt with an understandable outcome is often sufficient for a prototype. Record a request identifier rather than sensitive raw data when that helps investigate a failure.

Design an honest demonstration fallback

If the service is unavailable, a saved example can help explain the intended workflow. Label it as a prepared example and distinguish it from a live result. Do not silently show a recording or cached answer in a way that makes the viewer think the current request succeeded.

Prepare the fallback before you need it. Keep the sample input and expected output in the README and record a short walkthrough. This supports assessment when access fails, while preserving a clear account of what the project actually implements. The reviewer can then evaluate the design without being misled about the service state.

Rehearse failure on purpose

Try the main journey with a disconnected network, an invalid input and a simulated unsuccessful response in your development environment. Check that the input remains available and that the next action works. Restore the normal configuration afterward and repeat the successful journey using the same sample.

Include a short note about external dependencies and known limits in the submission. A judge should be able to understand whether a failure belongs to your implementation, an access requirement or an unavailable service. Use the demo checklist to combine these checks with a fresh-session rehearsal and link verification.

A short exercise to try

Create a failure rehearsal card for the main operation. Write the starting state, the interruption you will simulate, the text a user should see and the expected state of their work afterward. Run the card once before recording the final demo. For operations with side effects, include an uncertain result and verify that the interface does not encourage repeated sending. Keep these exercises in the development environment and identify any prepared failure response as a test fixture rather than a real provider event.

Use the current challenge brief to choose a workflow for these checks, and confirm the published deadline before preparing your final submission.

Sources