Precise exception types

When raising errors, choose the exception type that semantically matches the failure rather than a generic one. For example, invalid arguments or incompatible options should raise ValueError or TypeError, not a generic RuntimeError or AssertionError; include a clear, descriptive message explaining what went wrong and what the caller should do instead (e.g. “Tried to register a handler for an exception instance …; handlers can only be registered for exception classes or HTTP error codes.”).

When catching errors, avoid bare except: clauses — they also swallow SystemExit and KeyboardInterrupt, and make debugging much harder. Catch the narrowest exception type that covers the expected failure mode (e.g. except ValueError), or if you truly need to catch everything for cross-version compatibility reasons (such as Python 2’s ability to raise non-BaseException objects), explicitly document why and prefer except BaseException as e so the exception is still accessible, over a bare except:.

Example:

# Bad
if "data" in kwargs:
    raise RuntimeError("Client cannot provide both `json` and `data`")

try:
    data = dict(*args, **kwargs)
except:
    ...

# Good
if "data" in kwargs:
    raise ValueError("Client cannot provide both `json` and `data`")

try:
    data = dict(*args, **kwargs)
except TypeError as e:
    ...