onFailure

OnFailure is a term used in asynchronous programming to designate a callback or handler that is invoked when an operation fails to complete successfully. It is commonly paired with success or completion callbacks and is designed to allow implementers to react to errors, perform cleanup, or initiate retries. The exact form of onFailure and the data it receives vary by language and library, but it typically conveys an error condition via an exception, error object, or error code.

In practice, onFailure is used in networking, file I/O, background tasks, and other asynchronous flows. For example, in a callback-based HTTP client, onFailure may be called when a request cannot be executed due to connectivity issues, timeouts, or request cancellation; onResponse or the complementary success pathway handles successful outcomes. Some promise- or future-based APIs route failure through a catch or rejection handler that serves a similar purpose.

Design considerations include providing meaningful error information, preserving stack traces, avoiding leakage of sensitive data, and ensuring that onFailure runs on an appropriate thread or synchronization context if UI updates are required. It is common to implement retry logic, exponential backoff, or fallback strategies within onFailure handlers.

In library design, onFailure often coexists with onSuccess or onComplete, and developers should document the expected parameters, threading model, and any side effects. Proper use of onFailure improves robustness by centralizing error handling, enabling consistent user feedback, and facilitating recovery from fault conditions. See also: onSuccess, error handling, callbacks, promises, futures.