RUBY-3341 Document error handling in transactions

docs/reference/transactions.txt

@@ -76,6 +76,27 @@ which are read concern, write concern and read preference:
     collection.insert_one({hello: 'world'}, session: session)
   end
 
+Handling Errors Within the ``with_transaction`` Block
+-----------------------------------------------------
+
+If a command inside the ``with_transaction`` block fails, it may cause
+the transaction on the server to be aborted. This situation is normally handled
+transparently by the driver. However, if the application catches such an error
+and does not re-raise it, the driver will not be able to determine whether
+the transaction was aborted or not. The driver will then retry the block
+indefinitely.
+
+To avoid this situation, the application should re-raise errors that do not
+have ``TransientTransactionError`` in their error labels. For example:
+
+.. code-block:: ruby
+
+  session.with_transaction do
+    collection.insert_one({hello: 'world'}, session: session)
+  rescue Mongo::Error::OperationFailure => e
+    # Do something in response to the error
+    raise unless e.label?('TransientTransactionError')
+  end
 
 Low Level API
 =============
@@ -145,6 +166,14 @@ session if one is in progress:
   # ok
   c2.database.drop
 
+Handling Errors
+---------------
+
+If a command inside the transaction fails with, the transaction may be aborted
+on the server. Errors that abort transactions do not have
+``TransientTransactionError`` in their error labels. An attempt to commit such
+transaction will be rejected with ``NoSuchTransaction`` error.
+
 
 Retrying Commits
 ================