Design: Enhanced Error Handling for Generated Clients (#100)

[dougborg]

Summary

This PR adds a comprehensive design document for Issue #100: Enhanced error handling for generated OpenAPI clients.

What's Included

The design document (DESIGN_ISSUE_100.md) specifies:

Core Features

• Rich Exception Hierarchy: APIError → ClientError/ServerError with full HTTP context
• Parsed Error Models: Automatic parsing of error responses from OpenAPI specs
• Dual API Pattern: Simple (direct models) + Detailed (response wrappers with metadata)
• Multiple Success Codes: Support all 2xx codes including wildcards (2XX, 4XX, 5XX)
• Type Safety: No Union[Success, Error] types - exceptions for errors, models for success
• Backwards Compatible: HTTPException alias maintains existing code compatibility

Architecture

• Exception types with full context (status, method, URL, headers, request ID, body, parsed model)
• DetailedResponse[T] wrapper with fluent API (on().otherwise().resolve())
• Helper utilities (unwrap(), expect(), match(), type guards)
• HTTP client agnostic (httpx, requests, aiohttp)

Implementation Plan

10-phase rollout covering:

1. Core exceptions
2. Response wrappers
3. Utility functions
4. Service generator updates
5. Error creation functions
6. Simple API generation
7. Detailed API generation
8. Type guards
9. Integration testing
10. Documentation

Next Steps

1. Review & Approve Design: Community feedback on the proposed architecture
2. Implementation Roadmap: Break down into separate issues/PRs (see issue for proposed roadmap)
3. Phased Implementation: Tackle one phase at a time with focused PRs

Related

• Fixes #100
• Depends on static file infrastructure (#TBD - separate PR coming)

Request for Feedback

Please review:

• Overall architecture and design decisions
• API ergonomics (simple vs detailed patterns)
• Backwards compatibility approach
• Implementation phasing