docs: Add user-facing error handling guide to docs/sdk_users/

[bhuvan-somisetty]

Summary

The SDK defines three exceptions in src/hiero_sdk_python/exceptions.py — PrecheckError, MaxAttemptsError, and ReceiptStatusError — but there is no user-facing documentation explaining when they are thrown, what their attributes mean, or how to handle them.

The existing docs/sdk_developers/training/receipt_status_error.md is written for SDK contributors, not end users. The docs/sdk_users/ directory currently contains only running_examples.md and transaction_bytes.md — nothing about errors.

Current Behavior

A developer using the SDK has no reference for error handling. They must read source code to understand what to catch:

try:
    receipt = await transaction.execute(client).get_receipt(client)
except ???:  # PrecheckError? ReceiptStatusError? Something else?
    pass

Expected Behavior

Add docs/sdk_users/error_handling.md covering:

1. PrecheckError — thrown when a transaction fails pre-consensus validation. Attributes: status (ResponseCode), transaction_id.
2. MaxAttemptsError — thrown when all retry attempts to a node are exhausted. Attributes: node_id, last_error.
3. ReceiptStatusError — thrown when a receipt contains a non-SUCCESS status. Attributes: status, transaction_id, transaction_receipt.
4. How to read ResponseCode values to understand the failure reason.
5. A practical example showing all three in a single try/except block.
6. Retry and backoff guidance (when to retry vs. when to give up).

Example Output

from hiero_sdk_python.exceptions import PrecheckError, MaxAttemptsError, ReceiptStatusError
from hiero_sdk_python.response_code import ResponseCode

try:
    receipt = transaction.execute(client).get_receipt(client)
except PrecheckError as e:
    print(f"Transaction rejected before consensus: {e.status.name}")
except ReceiptStatusError as e:
    print(f"Transaction reached consensus but failed: {e.status.name}")
except MaxAttemptsError as e:
    print(f"Could not reach node {e.node_id}: {e.last_error}")

Why This Is Distinct

• docs/sdk_developers/training/receipt_status_error.md (closed issues Create docs/sdk_developers/training/precheck_error.md #876–Create docs/sdk_developers/training/receipt_status_error.md #878) covers one exception for contributors learning the internals.
• This issue requests a user-facing guide covering all three exceptions for developers building applications with the SDK.

Suggested Location

docs/sdk_users/error_handling.md with a link added to docs/sdk_users/running_examples.md and the main README.

Environment

• SDK version: v0.2.6
• Exceptions defined in: src/hiero_sdk_python/exceptions.py
• Response codes defined in: src/hiero_sdk_python/response_code.py

[exploreriii]

I am away from PC right now but we have examples covering the errors, i'm happy to assign this to you, perhaps you can refer to the examples we have? I do remember trying to catch all 3 errors, but i'm not sure if we ever finished that milestone.
Thanks

[github-actions]

@coderabbitai plan

[github-actions]

Hi @bhuvan-somisetty, this is the Assignment Bot.

Assigning you to this issue would exceed the limit of 2 open assignments.

Please resolve and merge your existing assigned issues before requesting new ones.

[coderabbitai]

Coding Plan

Summary

• Create a comprehensive user-facing error handling guide that mirrors the style and structure of existing docs/sdk_users/ documentation
• Document all three exception types with their attributes, trigger conditions, and code examples
• Include practical guidance on ResponseCode interpretation and retry strategies
• Integrate the new guide into the existing documentation navigation through README.md and running_examples.md cross-links

Implementation Steps

Phase 1: Create Error Handling Documentation

Create the primary user-facing guide covering all three exception types, ResponseCode interpretation, and practical guidance.

Create error_handling.md Document

Create docs/sdk_users/error_handling.md following the established documentation patterns from transaction_bytes.md with comprehensive error handling coverage.

• Document structure should follow the existing sdk_users/ pattern:

  • # Error Handling title with brief intro paragraph
  • ## Overview explaining the three-stage error model (precheck → network retry → receipt validation)
  • Separate ## section for each exception type
  • ## Understanding ResponseCode section
  • ## Practical Example with combined try/except
  • ## Retry and Backoff Guidance
  • ## See Also with links to examples/errors/ files and receipt_status_error.md

• PrecheckError section should document:

  • When raised: transaction fails pre-consensus validation (before reaching network consensus)
  • Attributes table: status (ResponseCode), transaction_id (TransactionId | None), message (str)
  • Common status codes that trigger it (e.g., INSUFFICIENT_TX_FEE, INVALID_SIGNATURE, TRANSACTION_EXPIRED)
  • Brief code example showing how to catch and inspect attributes

• MaxAttemptsError section should document:

  • When raised: all retry attempts exhausted or request timeout exceeded
  • Attributes table: node_id (str), last_error (BaseException | None), message (str)
  • Explanation that this wraps the last underlying error (could be a retried PrecheckError or gRPC transport error)
  • Brief code example showing how to catch and access last_error

• ReceiptStatusError section should document:

  • When raised: transaction reached consensus but receipt contains non-SUCCESS status
  • Attributes table: status (ResponseCode), transaction_id (TransactionId | None), transaction_receipt (TransactionReceipt), message (str)
  • Note about validate_status parameter controlling whether this is raised
  • Brief code example showing how to catch and inspect the receipt

• ResponseCode section should explain:

  • It's an IntEnum with ~394 named values
  • Key values: OK (0), SUCCESS (22), UNKNOWN (21), BUSY (12)
  • How to access the name and integer value (status.name, int(status))
  • The is_unknown property for synthetic codes
  • Note that there's no built-in human-readable description beyond the enum name

• Practical example should mirror the ticket's example output:

  • Show imports from hiero_sdk_python.exceptions and hiero_sdk_python.response_code
  • Single try block with transaction.execute(client).get_receipt(client)
  • Three except clauses in recommended order: PrecheckError, ReceiptStatusError, MaxAttemptsError
  • Print statements showing how to access key attributes

• Retry guidance section should cover:

  • Which errors are automatically retried by the SDK (BUSY, PLATFORM_NOT_ACTIVE, etc.)
  • When NOT to retry (INSUFFICIENT_TX_FEE, INVALID_SIGNATURE - fix the issue first)
  • When manual retry may help (MaxAttemptsError due to temporary network issues)
  • Backoff recommendation for manual retries

• Use ```python for all code fences, bold labels like **Attributes:** and **When raised:**, and relative links within sdk_users/

🤖 Prompt for AI agents

Create the file `docs/sdk_users/error_handling.md` following the established
style of existing `sdk_users/` guides (e.g., `transaction_bytes.md`).

The document should be structured as follows:
- `# Error Handling` title with a brief intro paragraph
- `## Overview` section explaining the three-stage error model: precheck →
network retry → receipt validation
- A dedicated `##` section for each of the three exception types:
`PrecheckError`, `MaxAttemptsError`, and `ReceiptStatusError`
- `## Understanding ResponseCode` section
- `## Practical Example` section with a combined try/except block
- `## Retry and Backoff Guidance` section
- `## See Also` section with relative links to `examples/errors/` files and
`receipt_status_error.md`

**PrecheckError section:**
- **When raised:** transaction fails pre-consensus validation (before reaching
network consensus)
- **Attributes table:** `status` (ResponseCode), `transaction_id` (TransactionId
| None), `message` (str)
- List common status codes: `INSUFFICIENT_TX_FEE`, `INVALID_SIGNATURE`,
`TRANSACTION_EXPIRED`
- Include a brief ` ```python ` code example showing how to catch and inspect
attributes

**MaxAttemptsError section:**
- **When raised:** all retry attempts exhausted or request timeout exceeded
- **Attributes table:** `node_id` (str), `last_error` (BaseException | None),
`message` (str)
- Explain that this wraps the last underlying error (could be a retried
PrecheckError or gRPC transport error)
- Include a brief ` ```python ` code example showing how to catch and access
`last_error`

**ReceiptStatusError section:**
- **When raised:** transaction reached consensus but receipt contains
non-SUCCESS status
- **Attributes table:** `status` (ResponseCode), `transaction_id` (TransactionId
| None), `transaction_receipt` (TransactionReceipt), `message` (str)
- Note about `validate_status` parameter controlling whether this is raised
- Include a brief ` ```python ` code example showing how to catch and inspect
the receipt

**Understanding ResponseCode section:**
- Describe it as an IntEnum with ~394 named values
- List key values: `OK` (0), `SUCCESS` (22), `UNKNOWN` (21), `BUSY` (12)
- Show how to access the name and integer value: `status.name`, `int(status)`
- Describe the `is_unknown` property for synthetic codes
- Note that there's no built-in human-readable description beyond the enum name

**Practical Example section:**
- Show imports from `hiero_sdk_python.exceptions` and
`hiero_sdk_python.response_code`
- Single try block with `transaction.execute(client).get_receipt(client)`
- Three except clauses in recommended order: `PrecheckError`,
`ReceiptStatusError`, `MaxAttemptsError`
- Print statements demonstrating access to key attributes

**Retry and Backoff Guidance section:**
- Which errors are automatically retried by the SDK (e.g., BUSY,
PLATFORM_NOT_ACTIVE)
- When NOT to retry (e.g., INSUFFICIENT_TX_FEE, INVALID_SIGNATURE — fix the
issue first)
- When manual retry may help (e.g., MaxAttemptsError due to temporary network
issues)
- Backoff recommendation for manual retries

Formatting rules:
- Use ` ```python ` for all code fences
- Use bold labels like `**Attributes:**` and `**When raised:**`
- Use relative links within `sdk_users/`

Phase 2: Integrate Documentation Links

Update existing documentation to cross-link to the new error handling guide.

Task 1: Update README.md

Add a link to the new error handling guide in the README's "For SDK Users" documentation section.

• Add entry under "### For SDK Users" (around line 62) following the existing pattern
• Use format: - **[Error Handling](https://github.com/hiero-ledger/hiero-sdk-python/blob/main/docs/sdk_users/error_handling.md)** - Guide to handling PrecheckError, ReceiptStatusError, and MaxAttemptsError
• Place it after the "Running Examples" link as a logical next topic for users learning the SDK

Task 2: Update running_examples.md

Add a cross-link to the error handling guide at the bottom of the running examples document.

• Add a new section or append to existing cross-link area at the bottom of the file
• Follow the pattern used for transaction_bytes.md: see [Error Handling](error_handling.md) with bullet summary
• Include brief mention of what the error handling doc covers (the three exception types)

🤖 Prompt for AI agents

Update two existing documentation files to cross-link to the newly created
`docs/sdk_users/error_handling.md`.

**1. Update `README.md`:**
- Locate the `### For SDK Users` subsection under `## Documentation` (around
line 62)
- Add the following entry after the "Running Examples" link:
`- **[Error
Handling](https://github.com/hiero-ledger/hiero-sdk-python/blob/main/docs/sdk_users/error_handling.md)**
- Guide to handling PrecheckError, ReceiptStatusError, and MaxAttemptsError`
- Match the formatting of existing entries in that section

**2. Update `docs/sdk_users/running_examples.md`:**
- Navigate to the bottom of the file
- Add a new cross-link section or append to the existing cross-link area,
following the same pattern used for `transaction_bytes.md`
- Reference the error handling guide using a relative link: `[Error
Handling](error_handling.md)`
- Include a brief mention of what the error handling doc covers (the three
exception types: `PrecheckError`, `ReceiptStatusError`, `MaxAttemptsError`)

Research

The Hiero Python SDK has three exception classes defined in src/hiero_sdk_python/exceptions.py that are raised during transaction execution and receipt fetching. The docs/sdk_users/ directory contains two existing user guides (running_examples.md and transaction_bytes.md) that follow a consistent style with ## Overview → content sections → ## See Also structure, Python code fences, and bold attribute labels. Working examples already exist in examples/errors/ demonstrating each exception type. The README.md has a "For SDK Users" subsection under "## Documentation" where doc links are added.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Create the file `docs/sdk_users/error_handling.md` following the established
style of existing `sdk_users/` guides (e.g., `transaction_bytes.md`).

The document should be structured as follows:
- `# Error Handling` title with a brief intro paragraph
- `## Overview` section explaining the three-stage error model: precheck →
network retry → receipt validation
- A dedicated `##` section for each of the three exception types:
`PrecheckError`, `MaxAttemptsError`, and `ReceiptStatusError`
- `## Understanding ResponseCode` section
- `## Practical Example` section with a combined try/except block
- `## Retry and Backoff Guidance` section
- `## See Also` section with relative links to `examples/errors/` files and
`receipt_status_error.md`

**PrecheckError section:**
- **When raised:** transaction fails pre-consensus validation (before reaching
network consensus)
- **Attributes table:** `status` (ResponseCode), `transaction_id` (TransactionId
| None), `message` (str)
- List common status codes: `INSUFFICIENT_TX_FEE`, `INVALID_SIGNATURE`,
`TRANSACTION_EXPIRED`
- Include a brief ` ```python ` code example showing how to catch and inspect
attributes

**MaxAttemptsError section:**
- **When raised:** all retry attempts exhausted or request timeout exceeded
- **Attributes table:** `node_id` (str), `last_error` (BaseException | None),
`message` (str)
- Explain that this wraps the last underlying error (could be a retried
PrecheckError or gRPC transport error)
- Include a brief ` ```python ` code example showing how to catch and access
`last_error`

**ReceiptStatusError section:**
- **When raised:** transaction reached consensus but receipt contains
non-SUCCESS status
- **Attributes table:** `status` (ResponseCode), `transaction_id` (TransactionId
| None), `transaction_receipt` (TransactionReceipt), `message` (str)
- Note about `validate_status` parameter controlling whether this is raised
- Include a brief ` ```python ` code example showing how to catch and inspect
the receipt

**Understanding ResponseCode section:**
- Describe it as an IntEnum with ~394 named values
- List key values: `OK` (0), `SUCCESS` (22), `UNKNOWN` (21), `BUSY` (12)
- Show how to access the name and integer value: `status.name`, `int(status)`
- Describe the `is_unknown` property for synthetic codes
- Note that there's no built-in human-readable description beyond the enum name

**Practical Example section:**
- Show imports from `hiero_sdk_python.exceptions` and
`hiero_sdk_python.response_code`
- Single try block with `transaction.execute(client).get_receipt(client)`
- Three except clauses in recommended order: `PrecheckError`,
`ReceiptStatusError`, `MaxAttemptsError`
- Print statements demonstrating access to key attributes

**Retry and Backoff Guidance section:**
- Which errors are automatically retried by the SDK (e.g., BUSY,
PLATFORM_NOT_ACTIVE)
- When NOT to retry (e.g., INSUFFICIENT_TX_FEE, INVALID_SIGNATURE — fix the
issue first)
- When manual retry may help (e.g., MaxAttemptsError due to temporary network
issues)
- Backoff recommendation for manual retries

Formatting rules:
- Use ` ```python ` for all code fences
- Use bold labels like `**Attributes:**` and `**When raised:**`
- Use relative links within `sdk_users/`
===============================================================================

Task: 2

Update two existing documentation files to cross-link to the newly created
`docs/sdk_users/error_handling.md`.

**1. Update `README.md`:**
- Locate the `### For SDK Users` subsection under `## Documentation` (around
line 62)
- Add the following entry after the "Running Examples" link:
`- **[Error
Handling](https://github.com/hiero-ledger/hiero-sdk-python/blob/main/docs/sdk_users/error_handling.md)**
- Guide to handling PrecheckError, ReceiptStatusError, and MaxAttemptsError`
- Match the formatting of existing entries in that section

**2. Update `docs/sdk_users/running_examples.md`:**
- Navigate to the bottom of the file
- Add a new cross-link section or append to the existing cross-link area,
following the same pattern used for `transaction_bytes.md`
- Reference the error handling guide using a relative link: `[Error
Handling](error_handling.md)`
- Include a brief mention of what the error handling doc covers (the three
exception types: `PrecheckError`, `ReceiptStatusError`, `MaxAttemptsError`)

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!

[github-actions]

Hello, this is CommunityCallBot.

This is a reminder that the Hiero Python SDK Community Call will begin in approximately 3 hours and 3 minutes (14:00 UTC).

The call is an open forum where contributors and users can discuss topics, raise issues, and influence the direction of the Python SDK.

Details:

• Time: 14:00 UTC
• Join Link: Zoom Meeting

Disclaimer: This is an automated reminder. Please verify the schedule here for any changes.