Add docs for how the client handles API errors and what contributors should do in new hooks

[Chucks1093]

Summary

Error handling in React Query hooks is inconsistent across the codebase. Some hooks surface errors to the UI, others swallow them silently. Contributors need a documented pattern to follow when writing new hooks so error handling is consistent from the start.

Scope

• Document the standard error handling pattern: what to do in onError, when to show a toast vs an inline error state, and when to let the error boundary catch it
• Add a note on how to distinguish network errors from API validation errors (4xx vs 5xx)
• Include a worked example of a hook that handles both error types correctly

Acceptance Criteria

• Pattern for onError is documented
• Toast vs inline error vs error boundary decision is explained
• 4xx vs 5xx distinction is covered
• Worked example is included

ETA: 12 hours

---

Coordinate on Telegram

[Peolite001]

i would love to work on this issue

[Ghadaffijr]

@Ghadaffijr has applied to work on this issue as part of the Stellar Wave Program's 6th wave.

I would love to take this on and can have the pr ready before the deadline.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Ghadaffijr to this issue.

[Lansa-18]

@Lansa-18 has applied to work on this issue as part of the Stellar Wave Program's 6th wave.

Hi, I'd like to work on this.
I'll write the error handling docs covering the standard onError pattern, the toast vs inline error vs error boundary decision tree, how to distinguish 4xx validation errors from 5xx network/server errors, and a worked example of a hook handling both correctly.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Lansa-18 to this issue.

[samjay8]

@samjay8 has applied to work on this issue as part of the Stellar Wave Program's 6th wave.

Kindly assign Chief.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @samjay8 to this issue.

[HassanKorey]

@HassanKorey has applied to work on this issue as part of the Stellar Wave Program's 6th wave.

Hi maintainer, kindly assign me

ℹ️ Repo Maintainers: To accept this application, review their application or assign @HassanKorey to this issue.

[Benedict315]

@Benedict315 has applied to work on this issue as part of the Stellar Wave Program's 6th wave.

Hello please assign

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Benedict315 to this issue.

[drips-wave]

Congratulations, @samjay8! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on June 30, 2026.

🧑‍💻 @samjay8: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊

[grantfox-oss]

🦊 GrantFox — @samjay8 has been assigned to this issue as part of the Official Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #460)
2. Your PR will be reviewed by the accesslayerorg maintainers

Good luck! Track your progress on GrantFox.

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox as part of the Official Campaign campaign!

@samjay8's PR #466 was approved and merged by @Chucks1093.

🏆 @samjay8: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (471 total points). Track your full progress on GrantFox.

👏 Great work, @samjay8! Keep contributing to accesslayerorg.

[drips-wave]

This issue has been completed by @samjay8 as part of the Stellar Wave Program's 6th Wave 🥳

😎 @samjay8: You earned 150 Points for completing this issue! After the current Wave ends, you'll be eligible for a percentage of the Wave's reward pool based on the percentage of total points you've earned. Learn more here. You can also Leave a review to share your experience working on this issue.

🧑‍💻 Repo maintainers: How'd the contributor do? Leave a review to share your experience working with them.