docs: add user-facing error handling guide to docs/sdk_users/ by bhuvan-somisetty · Pull Request #2249 · hiero-ledger/hiero-sdk-python

bhuvan-somisetty · 2026-05-07T03:39:23Z

Summary

Adds docs/sdk_users/error_handling.md — a new user-facing guide covering all three SDK exception types (PrecheckError, MaxAttemptsError, ReceiptStatusError) with attribute tables, when-raised descriptions, code examples, ResponseCode reference, a combined practical example, and retry/backoff guidance.
Updates README.md — adds an Error Handling link in the For SDK Users documentation section.
Updates docs/sdk_users/running_examples.md — adds a See Also cross-link at the bottom pointing to the new guide.

What this is NOT

The existing docs/sdk_developers/training/receipt_status_error.md (issues #876–#878) covers a single exception for SDK contributors. This guide is for application developers using the SDK and covers all three exceptions in one place.

Changes

File	Change
`docs/sdk_users/error_handling.md`	New file
`README.md`	Added Error Handling link under For SDK Users
`docs/sdk_users/running_examples.md`	Added See Also section at end

Test plan

Verify error_handling.md renders correctly on GitHub
Verify README link navigates to the correct file
Verify all relative links in See Also section resolve correctly
Verify code examples use correct import paths (hiero_sdk_python.exceptions, hiero_sdk_python.response_code)

codacy-production · 2026-05-07T03:40:26Z

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

_{NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer}
_{TIP This summary will be updated as you push new changes.}

coderabbitai · 2026-05-07T03:42:38Z

Walkthrough

Adds a user-facing error handling guide (docs/sdk_users/error_handling.md) describing PrecheckError, MaxAttemptsError, ReceiptStatusError, ResponseCode usage, examples, and retry guidance; adds links from README and running_examples to the new guide.

Changes

Error Handling Documentation

Layer / File(s)	Summary
Document Introduction `docs/sdk_users/error_handling.md` (lines 1–12)	Establishes the three-stage exception model: pre-consensus, retry-exhaustion, and post-consensus receipt validation.
PrecheckError `docs/sdk_users/error_handling.md` (lines 13–43)	Documents `PrecheckError` conditions and attributes (`status`, `transaction_id`, `message`) with an example.
MaxAttemptsError `docs/sdk_users/error_handling.md` (lines 44–70)	Describes `MaxAttemptsError`, attributes (`node_id`, `last_error`, `message`) and handling notes/examples.
ReceiptStatusError `docs/sdk_users/error_handling.md` (lines 71–98)	Documents `ReceiptStatusError` attributes (`status`, `transaction_id`, `transaction_receipt`) and `validate_status` behavior with example.
Response Code Reference `docs/sdk_users/error_handling.md` (lines 99–127)	Explains `ResponseCode` as `IntEnum`, shows `.name`, `int()`, and `.is_unknown`, and lists representative values.
Practical Examples & Guidance `docs/sdk_users/error_handling.md` (lines 128–149)	Combined try/except example covering all three exceptions and attribute-based branching.
Retry / Backoff Guidance `docs/sdk_users/error_handling.md` (lines 150–180)	Distinguishes SDK automatic retries from manual retry patterns; provides an exponential backoff example for `MaxAttemptsError`.
See Also Links `docs/sdk_users/error_handling.md` (lines 181–186)	Cross-references runnable examples and internal training documentation.

Repository Docs Links

Layer / File(s)	Summary
README link `README.md` (lines 62–63)	Adds "Error Handling" bullet/link under "For SDK Users".
Running examples See Also `docs/sdk_users/running_examples.md` (lines 2217–2220)	Adds a "See Also" bullet linking to the error handling documentation.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~2 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically describes the main change: adding a user-facing error handling guide to the docs/sdk_users/ directory.
Description check	✅ Passed	The description is well-related to the changeset, clearly summarizing the new documentation file, related updates to README and running_examples, and explaining the purpose and scope.
Linked Issues check	✅ Passed	The PR successfully addresses all requirements from issue `#2245`: adds error_handling.md documenting all three exceptions (PrecheckError, MaxAttemptsError, ReceiptStatusError) with attributes, when-raised descriptions, code examples, ResponseCode reference, practical example, and retry guidance; updates README and running_examples with appropriate links.
Out of Scope Changes check	✅ Passed	All changes are strictly in-scope: the new error_handling.md documentation file, README link addition, and running_examples.md cross-link are all directly aligned with issue `#2245` requirements and do not introduce unrelated modifications.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

📋 Issue Planner

Built with CodeRabbit's Coding Plans for faster development and fewer bugs.

View plan used: #2245

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai

Actionable comments posted: 5

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 95133046-c8d7-4227-9ae3-7d77af0442bd

📥 Commits

Reviewing files that changed from the base of the PR and between 343c42d and b06b433.

📒 Files selected for processing (3)

README.md
docs/sdk_users/error_handling.md
docs/sdk_users/running_examples.md

Akshat8510 · 2026-05-08T14:46:26Z

Hi @bhuvan-somisetty, thanks for the contribution! The branch is out-of-date, and all commits are not verified. This guide may help with GPG (-S) and DCO (-s) signing:

https://github.com/hiero-ledger/sdk-collaboration-hub/blob/main/guides/issue-progression/for-developers/signing.md

aceppaluni

@bhuvan-somisetty Please let us know if you need assistance with commit signing.

We're happy to help!

Signed-off-by: bhuvan-somisetty <somisettybhuvan5@gmail.com>

coderabbitai

Actionable comments posted: 2

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 89697b87-69d9-419b-9cc9-1dbddfbe2d5e

📥 Commits

Reviewing files that changed from the base of the PR and between b06b433 and 9286ee7.

📒 Files selected for processing (3)

README.md
docs/sdk_users/error_handling.md
docs/sdk_users/running_examples.md

coderabbitai · 2026-05-11T18:23:41Z

+
+## Understanding ResponseCode
+
+`ResponseCode` is an `IntEnum` with approximately 394 named values representing every status the Hedera network can return.


🧹 Nitpick | 🔵 Trivial | 💤 Low value

Consider rephrasing the specific number.

"Approximately 394 named values" is oddly precise. If the count is exact, remove "approximately." If it's an estimate, use "hundreds of" or similar phrasing that won't require updates as the API evolves.

Suggested alternatives

-`ResponseCode` is an `IntEnum` with approximately 394 named values representing every status the Hedera network can return. +`ResponseCode` is an `IntEnum` with hundreds of named values representing every status the Hedera network can return.

Or if the count is exact:

-`ResponseCode` is an `IntEnum` with approximately 394 named values representing every status the Hedera network can return. +`ResponseCode` is an `IntEnum` with 394 named values representing every status the Hedera network can return.

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

`ResponseCode` is an `IntEnum` with approximately 394 named values representing every status the Hedera network can return.

`ResponseCode` is an `IntEnum` with hundreds of named values representing every status the Hedera network can return.

coderabbitai · 2026-05-11T18:23:41Z

+- [examples/errors/precheck_error.py](../../examples/errors/precheck_error.py) — runnable `PrecheckError` example
+- [examples/errors/receipt_status_error.py](../../examples/errors/receipt_status_error.py) — runnable `ReceiptStatusError` example
+- [examples/errors/max_attempts_error.py](../../examples/errors/max_attempts_error.py) — runnable `MaxAttemptsError` example
+- [receipt_status_error.md](../sdk_developers/training/receipt_status_error.md) — internal training doc on receipt status errors


🧹 Nitpick | 🔵 Trivial | ⚡ Quick win

Consider removing the sdk_developers training link.

Line 186 links to an internal training document intended for SDK developers, but this error_handling.md guide is in docs/sdk_users/ for SDK users. Mixing audiences may confuse readers who expect user-focused resources only.

Consider either:

Removing this link entirely

Moving it to a separate "For SDK Developers" section if cross-linking is intentional

exploreriii

Yoru key is not set up correctly
https://github.com/hiero-ledger/hiero-sdk-python/pull/2249/commits

bhuvan-somisetty requested review from a team as code owners May 7, 2026 03:39

bhuvan-somisetty requested a review from nadineloepfe May 7, 2026 03:39

bhuvan-somisetty force-pushed the docs/error-handling-guide branch from b06b433 to 467bc05 Compare May 7, 2026 03:42

coderabbitai Bot reviewed May 7, 2026

View reviewed changes

Comment thread docs/sdk_users/error_handling.md Outdated

Comment thread README.md Outdated

Comment thread README.md Outdated

Comment thread README.md Outdated

Comment thread README.md Outdated

bhuvan-somisetty force-pushed the docs/error-handling-guide branch 2 times, most recently from 205f450 to 7c99680 Compare May 7, 2026 03:51

exploreriii added step: 1st 1st stage of the review approval process reviewer: community pull requests looking for community reviews labels May 7, 2026

aceppaluni mentioned this pull request May 7, 2026

docs: add SDK error handling guide #2246

Closed

2 tasks

aceppaluni added Duplicate PR Means there is a duplicate of the same PR and removed step: 1st 1st stage of the review approval process reviewer: community pull requests looking for community reviews labels May 7, 2026

github-actions Bot added the queue:junior-committer PR awaiting initial quality review label May 8, 2026

manishdait removed the Duplicate PR Means there is a duplicate of the same PR label May 8, 2026

github-actions Bot added the open to community review PR is open for community review and feedback label May 9, 2026

aceppaluni reviewed May 11, 2026

View reviewed changes

exploreriii marked this pull request as draft May 11, 2026 15:49

bhuvan-somisetty added 3 commits May 11, 2026 23:43

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

23305df

Signed-off-by: bhuvan-somisetty <somisettybhuvan5@gmail.com>

docs: add error handling guide link to README For SDK Users section

ba49986

Signed-off-by: bhuvan-somisetty <somisettybhuvan5@gmail.com>

docs: add error handling cross-link to running_examples.md

9286ee7

Signed-off-by: bhuvan-somisetty <somisettybhuvan5@gmail.com>

bhuvan-somisetty force-pushed the docs/error-handling-guide branch from 7c99680 to 9286ee7 Compare May 11, 2026 18:14

bhuvan-somisetty marked this pull request as ready for review May 11, 2026 18:20

coderabbitai Bot reviewed May 11, 2026

View reviewed changes

exploreriii requested changes May 11, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: add user-facing error handling guide to docs/sdk_users/#2249

docs: add user-facing error handling guide to docs/sdk_users/#2249
bhuvan-somisetty wants to merge 3 commits into
hiero-ledger:mainfrom
bhuvan-somisetty:docs/error-handling-guide

bhuvan-somisetty commented May 7, 2026

Uh oh!

codacy-production Bot commented May 7, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented May 7, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Akshat8510 commented May 8, 2026

Uh oh!

aceppaluni left a comment

Uh oh!

coderabbitai Bot left a comment

Uh oh!

coderabbitai Bot May 11, 2026

Uh oh!

coderabbitai Bot May 11, 2026

Uh oh!

exploreriii left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants


		## Understanding ResponseCode

		`ResponseCode` is an `IntEnum` with approximately 394 named values representing every status the Hedera network can return.

	`ResponseCode` is an `IntEnum` with approximately 394 named values representing every status the Hedera network can return.
	`ResponseCode` is an `IntEnum` with hundreds of named values representing every status the Hedera network can return.

Conversation

bhuvan-somisetty commented May 7, 2026

Summary

What this is NOT

Changes

Test plan

Uh oh!

codacy-production Bot commented May 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Up to standards ✅

Uh oh!

coderabbitai Bot commented May 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Akshat8510 commented May 8, 2026

Uh oh!

aceppaluni left a comment

Choose a reason for hiding this comment

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

coderabbitai Bot May 11, 2026

Choose a reason for hiding this comment

Uh oh!

coderabbitai Bot May 11, 2026

Choose a reason for hiding this comment

Uh oh!

exploreriii left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

codacy-production Bot commented May 7, 2026 •

edited

Loading

coderabbitai Bot commented May 7, 2026 •

edited

Loading