docs: error handling & expected exceptions and how to handle them #25

[CoolatMax]

Pull Request

Description

Please include a summary of the changes and the related issue. Include relevant motivation and context.

Fixes #(issue number)

Type of Change

Please delete options that are not relevant.

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Code refactoring
• Performance improvement
• Test addition/update

Changes Made

• Created docs/user-guide/error-handling.md covering GPTClientInitializationError, RemediationError, and ValueError triggers.

• Detailed the retry_with_backoff mechanism found in hier_config_gpt/clients/utils.py.

• Added an implementation example showing how to handle both SDK-specific and native provider (OpenAI/Anthropic) exceptions.

• Updated mkdocs.yml to include the new section in the sidebar under "User Guide."

Testing

Describe the tests that you ran to verify your changes:

• I have performed manual validation to ensure the documentation aligns with the current codebase:
• Manual testing performed: Verified exception names and export paths via terminal.
• Documentation Preview: Ran mkdocs serve to verify the link renders correctly and the navigation is functional.

Test Configuration

• Python version: 3.10+

• Operating System: Linux (Codespace)

• LLM Provider tested: Logic verified via utils.py and quorum.py source analysis.

Checklist

• My code follows the project's code style
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• I have updated CHANGELOG.md
• I have checked that my PR is not a duplicate

Screenshots/Logs (if applicable)

Additional Notes

The documentation specifically highlights the "leaky abstraction" where provider-specific errors (like RateLimitError) are allowed to propagate, ensuring users know they must still import and catch native provider exceptions alongside the library's custom ones.

Closes Issue: #25