docs: add receipt_status_error.md and example script (fixes #878) (#883)

Signed-off-by: jaideepkathiresan <jvk7557@gmail.com>

Author: jaideepkathiresan

CHANGELOG.md

@@ -8,6 +8,10 @@ This changelog is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.
 
 ### Added
 
+- Add comprehensive documentation for `ReceiptStatusError` in `docs/sdk_developers/training/receipt_status_error.md`
+- Add practical example `examples/errors/receipt_status_error.py` demonstrating transaction error handling
+- Document error handling patterns and best practices for transaction receipts
+
 - Add detail to `token_airdrop.py` and `token_airdrop_cancel.py`
 - Add workflow: github bot to respond to unverified PR commits (#750)
 - Add workflow: bot workflow which notifies developers of workflow failures in their pull requests.

docs/sdk_developers/training/receipt_status_error.md

@@ -0,0 +1,68 @@
+# ReceiptStatusError
+
+This guide explains `ReceiptStatusError` in the Hiero SDK, how it differs from other errors, and how to handle it effectively.
+
+## Error Handling Overview
+
+Many developers assume that if `execute()` doesn't throw an exception, the transaction or query succeeded. However, failures can occur at different stages:
+
+1.  **Precheck (Before Submission):**
+    *   Occurs if the transaction is malformed or fails initial validation by the node.
+    *   The SDK raises a `PrecheckError` (or similar) immediately.
+    *   The transaction never reaches consensus.
+
+2.  **Network/Node Retry Failures:**
+    *   Occurs if the SDK cannot reach a node or receives transient errors (e.g., `BUSY`).
+    *   The SDK automatically retries up to a limit.
+    *   If retries are exhausted, a `MaxAttemptsError` or `TimeoutError` is raised.
+
+3.  **Receipt Status Errors (Post-Consensus):**
+    *   Occurs **after** the network reaches consensus on the transaction.
+    *   The transaction was successfully submitted and processed, but the logic failed (e.g., insufficient funds, token supply full, invalid signature for the specific operation).
+    *   This is where `ReceiptStatusError` comes in.
+
+## What is ReceiptStatusError?
+
+`ReceiptStatusError` is an exception that represents a failure during the **consensus/execution** phase.
+
+*   **Timing:** It happens after the transaction is submitted and processed by the network.
+*   **Content:** It contains the `transaction_receipt`, which holds the status code (e.g., `INSUFFICIENT_ACCOUNT_BALANCE`) and other metadata.
+*   **Usage:** You must explicitly check the receipt status or configure your client/transaction to throw this error.
+
+## Handling ReceiptStatusError
+
+When you execute a transaction, you typically get a receipt. You should check the status of this receipt.
+
+```python
+from hiero_sdk_python.response_code import ResponseCode
+from hiero_sdk_python.exceptions import ReceiptStatusError
+
+# ... client and transaction setup ...
+
+try:
+    # Execute the transaction
+    receipt = tx.execute(client)
+
+    # Check if the status is SUCCESS
+    if receipt.status != ResponseCode.SUCCESS:
+        # Raise the specific error with details
+        raise ReceiptStatusError(receipt.status, tx.transaction_id, receipt)
+
+    print("Transaction succeeded!")
+
+except ReceiptStatusError as e:
+    print(f"Transaction failed post-consensus: {e}")
+    print(f"Status Code: {e.status}")
+    print(f"Transaction ID: {e.transaction_id}")
+    # You can access the full receipt for debugging
+    # print(e.transaction_receipt)
+
+except Exception as e:
+    print(f"An unexpected error occurred: {e}")
+```
+
+## Summary
+
+*   **Precheck errors** happen *before* the network processes the transaction.
+*   **ReceiptStatusErrors** happen *after* the network processes the transaction but finds it invalid according to ledger rules.
+*   Always check `receipt.status` to ensure your transaction actually did what you intended.

examples/errors/receipt_status_error.py

@@ -0,0 +1,75 @@
+#!/usr/bin/env python3
+"""
+Example demonstrating how to handle ReceiptStatusError in the Hiero SDK.
+
+run: 
+uv run examples/errors/receipt_status_error.py
+python examples/errors/receipt_status_error.py
+"""
+import os
+import dotenv
+
+from hiero_sdk_python.client.client import Client
+from hiero_sdk_python.account.account_id import AccountId
+from hiero_sdk_python.crypto.private_key import PrivateKey
+from hiero_sdk_python.response_code import ResponseCode
+from hiero_sdk_python.tokens.token_associate_transaction import TokenAssociateTransaction
+from hiero_sdk_python.tokens.token_id import TokenId
+from hiero_sdk_python.exceptions import ReceiptStatusError
+
+dotenv.load_dotenv()
+
+def main():
+    # Initialize the client
+    # For this example, we assume we are running against a local node or testnet
+    # You would typically load these from environment variables
+    operator_id_str = os.environ.get("OPERATOR_ID", "")
+    operator_key_str = os.environ.get("OPERATOR_KEY", "")
+    
+    try:
+        operator_id = AccountId.from_string(operator_id_str)
+        operator_key = PrivateKey.from_string(operator_key_str)
+    except Exception as e:
+        print(f"Error parsing operator credentials: {e}")
+        return
+
+    client = Client()
+    client.set_operator(operator_id, operator_key)
+
+    # Create a  transaction that is likely to fail post-consensus
+    # Here we try to associate a non-existent token
+    
+    print("Creating transaction...")
+    transaction = TokenAssociateTransaction() \
+        .set_account_id(operator_id) \
+        .add_token_id(TokenId(0,0,3)) \
+        .freeze_with(client) \
+        .sign(operator_key)
+
+    try:
+        print("Executing transaction...")
+        # execute() submits the transaction to the network and returns a receipt
+        # Note: this does NOT automatically raise an exception if the transaction fails post-consensus.
+        receipt = transaction.execute(client)
+        print(f"Transaction submitted. ID: {receipt.transaction_id}")
+                
+        # Check if the execution raised something other than SUCCESS
+        # If not, we raise our custom ReceiptStatusError for handling.
+        if receipt.status != ResponseCode.SUCCESS:
+             raise ReceiptStatusError(receipt.status, receipt.transaction_id, receipt)
+        # If we reach here, the transaction succeeded
+        print("Transaction successful!")
+
+    # This exception is raised when the transaction raised something other than SUCCESS
+    except ReceiptStatusError as e:
+        print("\nCaught ReceiptStatusError!")
+        print(f"Status: {e.status} ({ResponseCode(e.status).name})")
+        print(f"Transaction ID: {e.transaction_id}")
+        print("This error means the transaction reached consensus but failed logic execution.")
+        
+    # Catch all for unexpected errors
+    except Exception as e:
+        print(f"\nAn unexpected error occurred: {e}")
+
+if __name__ == "__main__":
+    main()