[Enhancement] Add typed error hierarchy with specific exception classes for common failure modes

[deepgram-robot]

Summary

Add a typed error hierarchy that maps Deepgram API error responses to specific Python exception classes, enabling precise error handling without string parsing or status code inspection.

Problem it solves

Currently, Deepgram API errors surface as generic exceptions that require inspecting status codes or parsing error messages manually. Developers building production voice applications need to handle rate limits (429), authentication failures (401), invalid parameters (400), and server errors (500) differently — for example, retrying on 429 with backoff but failing fast on 401. A typed hierarchy enables idiomatic try/except patterns for each failure mode, which is the standard approach across modern Python SDKs and what developers expect.

Proposed API

from deepgram.errors import (
    DeepgramAPIError,            # Base class for all API errors
    DeepgramRateLimitError,      # 429 — includes retry_after
    DeepgramAuthenticationError, # 401/403
    DeepgramValidationError,     # 400 — includes field-level details
    DeepgramServerError,         # 500/502/503
    DeepgramTimeoutError,        # Request timeout
    DeepgramWebSocketError,      # WebSocket-specific (close code + reason)
)

try:
    result = await client.listen.rest.v("1").transcribe_url(source, options)
except DeepgramRateLimitError as e:
    await asyncio.sleep(e.retry_after)
    # retry...
except DeepgramAuthenticationError:
    raise SystemExit("Invalid API key")
except DeepgramValidationError as e:
    logger.error(f"Bad request: {e.details}")

Acceptance criteria

• Each HTTP status code range maps to a specific exception class
• DeepgramRateLimitError exposes retry_after from response headers
• DeepgramValidationError includes structured error details from response body
• WebSocket errors have a dedicated subclass with close code and reason
• Documented with usage example
• Compatible with existing API (existing error handling continues to work)
• All new exception classes are importable from the top-level deepgram package

---

Raised by the DX intelligence system.