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 Enhance generated HTTPException: rich context, parsed error models, configurable handling #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

[Copilot]

Pull Request Overview

This PR introduces a comprehensive design document for implementing enhanced error handling in generated OpenAPI Python clients. The design addresses the need for rich, structured error handling with full HTTP context while maintaining backward compatibility and type safety.

Key Changes:

• Defines a three-tier exception hierarchy (APIError → ClientError/ServerError) with full HTTP context
• Introduces dual API pattern: simple (direct model returns) and detailed (response wrappers with metadata)
• Specifies automatic parsing of error response models from OpenAPI specifications
• Outlines 10-phase implementation plan spanning core exceptions, response wrappers, utilities, and code generation

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[dougborg]

✅ Addressed all Copilot review comments:

1. Bare except clause (line ~831): Changed from to to avoid catching system-level exceptions

2. Broad exception handling (line ~857): Narrowed from to for error model parsing

3. Misleading comment (line ~872): Improved status code classification logic with clearer comments explaining defensive handling and added fallback to APIError for unexpected status codes

4. Missing documentation (line ~1027): Added field to OpReturnType with clear documentation explaining it's set when OpenAPI spec uses '2XX' wildcard pattern, plus added inline comments in template code

All changes pushed in commit 4238443.