onDeliveryFailure

onDeliveryFailure is a callback or event in asynchronous message delivery systems that is triggered when an attempted delivery cannot be completed due to an error. It is commonly provided by client libraries or frameworks that implement producer-side delivery guarantees, and it complements success and retry semantics by offering a hook to handle unrecoverable failures.

The handler typically receives contextual information such as an error object or exception, an identifier for the failed message, the destination or topic, and optional metadata like dispatch timestamp and the number of retries already attempted. Some implementations also include the original payload or encoding details.

On invocation, the onDeliveryFailure handler is expected to perform remediation. Common actions include logging the failure, applying a backoff or retry policy, routing the message to a dead-letter queue, alerting operators, and ensuring idempotent or deduplicated processing for subsequent handling.

This pattern is used across messaging and eventing stacks, including Kafka-like producers, AMQP, MQTT clients, and cloud notification libraries. It is often part of a broader delivery strategy that also includes onDeliverySuccess and configurable retry and dead-letter policies.

Design considerations include thread safety, avoiding side effects in the callback, preserving message identity for deduplication, and maintaining ordering guarantees where needed. Implementers should align on what constitutes a non-recoverable failure and how long to retain failed messages.

In practice, developers wire onDeliveryFailure to their error handling and monitoring systems, choosing between logging, dead-lettering, retries, or human-in-the-loop intervention depending on the application's reliability requirements.