From eacdb09cd7e80cffdfdd138d85319e3e15aea34f Mon Sep 17 00:00:00 2001
From: Kaushik Raina <103954755+k-raina@users.noreply.github.com>
Date: Wed, 19 Feb 2025 22:45:47 +0530
Subject: [PATCH] Add TransactionAbortableException and Timeout Exception
 handling instruction in docs (#18942)

Add instruction for handing TransactionAbortableException and TimeoutException at application side.

Reviewers: Justine Olshan <jolshan@confluent.io>
---
 docs/upgrade.html | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/docs/upgrade.html b/docs/upgrade.html
index 6d29bcc8082..f0521ece048 100644
--- a/docs/upgrade.html
+++ b/docs/upgrade.html
@@ -361,6 +361,14 @@
                     timestamp of more than 1 hour in the future will be rejected when message.timestamp.type=CreateTime is set.
                     See <a href="https://cwiki.apache.org/confluence/display/KAFKA/KIP-1030%3A+Change+constraints+and+default+values+for+various+configurations">KIP-1030</a> 
                 </li>
+                <li>Introduced in KIP-890, the <code>TransactionAbortableException</code> enhances error handling within transactional operations by clearly indicating scenarios where transactions should be aborted due to errors. It is important for applications to properly manage both <code>TimeoutException</code> and <code>TransactionAbortableException</code> when working with transaction producers.</li>
+                <ul>
+                    <li><b>TimeoutException:</b> This exception indicates that a transactional operation has timed out. Given the risk of message duplication that can arise from retrying operations after a timeout (potentially violating exactly-once semantics), applications should treat timeouts as reasons to abort the ongoing transaction.</li>
+                    <li><b>TransactionAbortableException:</b> Specifically introduced to signal errors that should lead to transaction abortion, ensuring this exception is properly handled is critical for maintaining the integrity of transactional processing.</li>
+                    <li>To ensure seamless operation and compatibility with future Kafka versions, developers are encouraged to update their error-handling logic to treat both exceptions as triggers for aborting transactions. This approach is pivotal for preserving exactly-once semantics.</li>
+                    <li> See <a href="https://cwiki.apache.org/confluence/display/KAFKA/KIP-890%3A+Transactions+Server-Side+Defense">KIP-890</a> and
+                    <a href="https://cwiki.apache.org/confluence/display/KAFKA/KIP-1050%3A+Consistent+error+handling+for+Transactions">KIP-1050</a> for more details </li>
+                </ul>
             </ul>
         </li>
     </ul>