Retry, timeout, or fail fast: choosing the right error behavior in small tools

Small tools should not retry every error. The right behavior depends on whether the failure is temporary, slow, or logically impossible.

Retry is useful for flaky network calls, rate-limit windows, transient lock files, and services that sometimes return a temporary failure. Timeout is useful when a command might hang forever because a process, socket, or browser page never finishes. Fail fast is useful when the input is invalid, a required file is missing, credentials are absent, or the request is forbidden. Retrying a bad input only hides the real issue.

A practical decision table starts with the question: could the same request work a few seconds later without changing the input? If yes, retry with a small limit and visible delay. If no, fail fast and show the missing condition. If the operation might never return, add a timeout even if you also retry.

Retries should also be observable. A tool that silently retries for two minutes feels broken. Print the attempt number, short reason, and next delay. Avoid retrying destructive operations unless the operation is idempotent or protected by a unique request key. A repeated create call can produce duplicates if the first request actually succeeded but the response was lost.

Timeouts need clear ownership. Is the timeout for connecting, reading, the whole command, or a single step? A vague timeout message gives little help. A better message says which step waited too long and what the user can check next.

The best small-tool behavior is predictable: fail fast for bad inputs, timeout for hangs, retry only for plausible temporary failures, and always report what was attempted.

Retry, timeout, or fail fast: choosing the right error behavior in small tools

// COMMENTS

ON THIS PAGE