Support Client-Level Exception Handlers for httpx.Client and httpx.AsyncClient

[dhruvjain1512]

🚀 Feature Request: Client-Level Exception Handlers for httpx.Client and httpx.AsyncClient

Problem Statement

Currently, httpx.Client and httpx.AsyncClient do not support registering custom exception handlers at the client level.
Developers are forced to wrap every request call with repetitive try/except blocks whenever consistent error handling is required.

This results in:

• Repetitive boilerplate across multiple request sites.
• Increased code maintenance complexity.
• Higher chances of missing or inconsistent error handling in large projects.

In many real-world scenarios, applications need uniform exception management across all outgoing HTTP calls from a shared client instance.

---

Proposed Solution

Introduce the ability to register custom exception handlers at the client level, allowing centralized and automatic handling of all exceptions raised during requests.

Key aspects of the proposed behavior:

• Allow developers to pass a mapping of exception types to handler callables during client creation, e.g.:

  def handle_timeout(exc):
      logger.warning(f"Request timed out: {exc}")
      return None
  
  client = httpx.Client(exception_handlers={httpx.TimeoutException: handle_timeout})

• When any request made through the client raises a matching exception:
  • The corresponding handler should automatically be invoked.
  • Handlers for more specific exception types should take precedence over base classes.
  • Handlers should support inheritance-based type matching.
• Both synchronous and asynchronous clients should support this feature in a consistent manner.

---

Example Use Case

def log_connection_error(exc):
    logger.error(f"Connection issue: {exc}")
    raise CustomConnectionError from exc

def retry_on_timeout(exc):
    logger.info("Retrying due to timeout...")
    return retry_request()

client = httpx.Client(
    exception_handlers={
        httpx.ConnectError: log_connection_error,
        httpx.TimeoutException: retry_on_timeout
    }
)

# No need for repetitive try/except blocks
response = client.get("https://example.com/data")

This pattern ensures that all requests from a client share the same consistent error handling behavior without requiring per-call wrappers.

---

Expected Behavior

• Registered exception handlers automatically intercept exceptions raised within client.request(), client.get(), client.post(), etc.
• More specialized exception handlers (e.g., httpx.ReadTimeout) take precedence over general ones (e.g., httpx.RequestError).
• Compatible with both synchronous and asynchronous interfaces.
• Maintains backward compatibility for clients without registered handlers.

---

Benefits

• Reduces repetitive boilerplate and improves code clarity.
• Centralizes error handling for better maintainability and testability.
• Simplifies integration with logging, monitoring, and retry frameworks.
• Encourages a clean, declarative configuration style consistent with modern Python design patterns.

---

Discussion Points

• Should handler callables return fallback responses, re-raise exceptions, or both (configurable)?
• How to propagate handler return values in async contexts?
• Should exception_handlers be modifiable post client initialization?

---

References & Inspiration

• Similar patterns exist in frameworks such as FastAPI (exception_handlers), aiohttp middlewares, and requests-hooks.
• Would align with modern best practices for composable HTTP clients and centralized observability.