feat(errors): align error codes with Go canonical list

Expand the error registry to cover all 19 HTTP + 6 WebSocket-frame
codes now defined in the canonical error-code set. Exception routing now
consults a code→exception map first and falls back to HTTP-status
routing for responses without codes.

Keep the existing six exception classes and retire no public API.
bad_request and invalid_request are aliased to validation_error via
DEPRECATED_CODE_ALIASES so servers still emitting them route through
canonical_code() without breaking older clients.

Bump 0.2.2 → 0.2.3. 87/87 tests pass.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: Mlaz-code

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sharpapi"
-version = "0.2.2"
+version = "0.2.3"
 description = "Official Python SDK for the SharpAPI real-time sports betting odds API"
 readme = "README.md"
 license = "MIT"

src/sharpapi/__init__.py

@@ -21,6 +21,8 @@
 from .async_client import AsyncSharpAPI
 from .client import SharpAPI
 from .exceptions import (
+    ERROR_CODE_DESCRIPTIONS,
+    ERROR_CODE_TO_EXCEPTION,
     AuthenticationError,
     RateLimitedError,
     SharpAPIError,
@@ -51,7 +53,7 @@
 )
 from .streaming import EventStream
 
-__version__ = "0.2.1"
+__version__ = "0.2.3"
 
 __all__ = [
     # Clients
@@ -86,6 +88,9 @@
     "StreamError",
     "TierRestrictedError",
     "ValidationError",
+    # Error-code registry
+    "ERROR_CODE_DESCRIPTIONS",
+    "ERROR_CODE_TO_EXCEPTION",
     # Utilities
     "american_to_decimal",
     "american_to_probability",

src/sharpapi/_base.py

@@ -7,17 +7,19 @@
 import httpx
 
 from .exceptions import (
+    ERROR_CODE_TO_EXCEPTION,
     AuthenticationError,
     RateLimitedError,
     SharpAPIError,
     TierRestrictedError,
     ValidationError,
+    canonical_code,
 )
 from .models import APIResponse, RateLimitInfo, ResponseMeta
 
 DEFAULT_BASE_URL = "https://api.sharpapi.io"
 DEFAULT_TIMEOUT = 30.0
-USER_AGENT = "sharpapi-python/0.2.2"
+USER_AGENT = "sharpapi-python/0.2.3"
 
 RETRY_STATUSES = frozenset({502, 503, 504})
 RETRY_MAX_ATTEMPTS = 3
@@ -90,6 +92,30 @@ def handle_errors(response: httpx.Response) -> None:
         code = body.get("code", "unknown_error")
     status = response.status_code
 
+    # Resolve deprecated code aliases (bad_request, invalid_request → validation_error).
+    code = canonical_code(code)
+
+    # Prefer the canonical code→exception mapping for well-known codes; fall back
+    # to HTTP-status-based routing for responses that omit an error code.
+    exc_class = ERROR_CODE_TO_EXCEPTION.get(code or "")
+    if exc_class is TierRestrictedError:
+        raise TierRestrictedError(
+            error_msg,
+            code=code,
+            status=status,
+            required_tier=body.get("required_tier"),
+        )
+    if exc_class is RateLimitedError:
+        raise RateLimitedError(
+            error_msg,
+            code=code,
+            status=status,
+            retry_after=body.get("retry_after"),
+        )
+    if exc_class is not None and exc_class is not SharpAPIError:
+        raise exc_class(error_msg, code=code, status=status)
+
+    # No canonical code match — route by HTTP status.
     if status == 401:
         raise AuthenticationError(error_msg, code=code, status=status)
     elif status == 403:

src/sharpapi/exceptions.py

@@ -1,4 +1,9 @@
-"""SharpAPI exceptions."""
+"""SharpAPI exceptions and canonical error-code registry.
+
+The error codes here mirror ``pkg/errcodes/errcodes.go`` in sharp-api-go, which
+is the single source of truth for every code the API emits. Keep this file in
+sync when new codes are added upstream.
+"""
 
 from __future__ import annotations
 
@@ -13,7 +18,12 @@ def __init__(self, message: str, code: str | None = None, status: int | None = N
 
 
 class AuthenticationError(SharpAPIError):
-    """API key is missing or invalid (401)."""
+    """API key is missing, invalid, expired, disabled, or token is rejected.
+
+    Raised for HTTP 401 responses and any of the auth-related error codes
+    (``missing_api_key``, ``invalid_api_key``, ``expired_api_key``,
+    ``disabled_api_key``, ``invalid_token``, ``unauthorized``).
+    """
 
 
 class TierRestrictedError(SharpAPIError):
@@ -31,7 +41,7 @@ def __init__(
 
 
 class RateLimitedError(SharpAPIError):
-    """Too many requests (429)."""
+    """Too many requests (429) — rate-limited, backpressure, or concurrent cap."""
 
     def __init__(
         self,
@@ -49,4 +59,124 @@ class ValidationError(SharpAPIError):
 
 
 class StreamError(SharpAPIError):
-    """Error during SSE streaming."""
+    """Error during SSE or WebSocket streaming."""
+
+
+# =============================================================================
+# Canonical error-code registry
+#
+# Mirrors sharp-api-go/pkg/errcodes/errcodes.go. When upstream adds a new code,
+# add it here too and update the matching description. Each code maps to the
+# Python exception class that ``handle_errors`` (in ``_base.py``) raises for it.
+# =============================================================================
+
+# HTTP error codes — emitted via REST handlers (httputil.WriteJSONError).
+BACKPRESSURE = "backpressure"
+CONCURRENT_REQUEST_CAP = "concurrent_request_cap"
+DISABLED_API_KEY = "disabled_api_key"
+EXPIRED_API_KEY = "expired_api_key"
+GONE = "gone"
+INTERNAL_ERROR = "internal_error"
+INVALID_API_KEY = "invalid_api_key"
+INVALID_TOKEN = "invalid_token"
+METHOD_NOT_ALLOWED = "method_not_allowed"
+MISSING_API_KEY = "missing_api_key"
+NOT_FOUND = "not_found"
+RATE_LIMITED = "rate_limited"
+SERVICE_UNAVAILABLE = "service_unavailable"
+TIER_RESTRICTED = "tier_restricted"
+TOO_MANY_STREAMS = "too_many_streams"
+UNAUTHORIZED = "unauthorized"
+UNKNOWN_ENDPOINT = "unknown_endpoint"
+UPSTREAM_ERROR = "upstream_error"
+VALIDATION_ERROR = "validation_error"
+
+# WebSocket frame error codes — emitted in "error" message frames.
+WS_ALREADY_AUTHENTICATED = "already_authenticated"
+WS_INVALID_MESSAGE = "invalid_message"
+WS_MISSING_CHANNELS = "missing_channels"
+WS_MISSING_TOKEN = "missing_token"
+WS_NOT_AUTHENTICATED = "not_authenticated"
+WS_UNKNOWN_MESSAGE_TYPE = "unknown_message_type"
+
+#: Human-readable descriptions for every canonical code.
+ERROR_CODE_DESCRIPTIONS: dict[str, str] = {
+    # HTTP
+    BACKPRESSURE: "Server is shedding load; retry shortly.",
+    CONCURRENT_REQUEST_CAP: "Too many in-flight requests for this API key.",
+    DISABLED_API_KEY: "API key has been disabled.",
+    EXPIRED_API_KEY: "API key has expired.",
+    GONE: "Resource is no longer available.",
+    INTERNAL_ERROR: "Unexpected server error.",
+    INVALID_API_KEY: "API key is invalid.",
+    INVALID_TOKEN: "Bearer token is invalid or malformed.",
+    METHOD_NOT_ALLOWED: "HTTP method not allowed on this endpoint.",
+    MISSING_API_KEY: "No API key provided.",
+    NOT_FOUND: "Resource not found.",
+    RATE_LIMITED: "Rate limit exceeded; see Retry-After header.",
+    SERVICE_UNAVAILABLE: "Service is temporarily unavailable.",
+    TIER_RESTRICTED: "Current subscription tier does not include this feature.",
+    TOO_MANY_STREAMS: "Maximum concurrent WebSocket/SSE streams exceeded.",
+    UNAUTHORIZED: "Authentication required.",
+    UNKNOWN_ENDPOINT: "Endpoint does not exist.",
+    UPSTREAM_ERROR: "Upstream data source error.",
+    VALIDATION_ERROR: "Request parameters failed validation.",
+    # WebSocket
+    WS_ALREADY_AUTHENTICATED: "Auth frame sent on an already-authenticated connection.",
+    WS_INVALID_MESSAGE: "Malformed WebSocket frame.",
+    WS_MISSING_CHANNELS: "Subscribe frame had no channels.",
+    WS_MISSING_TOKEN: "Auth frame had no token.",
+    WS_NOT_AUTHENTICATED: "Action requires authentication first.",
+    WS_UNKNOWN_MESSAGE_TYPE: "Unknown WebSocket message type.",
+}
+
+#: Map each canonical code to the SharpAPIError subclass ``handle_errors`` raises.
+ERROR_CODE_TO_EXCEPTION: dict[str, type[SharpAPIError]] = {
+    # Auth family → AuthenticationError
+    MISSING_API_KEY: AuthenticationError,
+    INVALID_API_KEY: AuthenticationError,
+    EXPIRED_API_KEY: AuthenticationError,
+    DISABLED_API_KEY: AuthenticationError,
+    INVALID_TOKEN: AuthenticationError,
+    UNAUTHORIZED: AuthenticationError,
+    # Tier
+    TIER_RESTRICTED: TierRestrictedError,
+    # Rate / load shedding
+    RATE_LIMITED: RateLimitedError,
+    BACKPRESSURE: RateLimitedError,
+    CONCURRENT_REQUEST_CAP: RateLimitedError,
+    TOO_MANY_STREAMS: RateLimitedError,
+    # Validation
+    VALIDATION_ERROR: ValidationError,
+    # Streaming frames
+    WS_ALREADY_AUTHENTICATED: StreamError,
+    WS_INVALID_MESSAGE: StreamError,
+    WS_MISSING_CHANNELS: StreamError,
+    WS_MISSING_TOKEN: StreamError,
+    WS_NOT_AUTHENTICATED: StreamError,
+    WS_UNKNOWN_MESSAGE_TYPE: StreamError,
+    # Everything else falls through to SharpAPIError
+    GONE: SharpAPIError,
+    INTERNAL_ERROR: SharpAPIError,
+    METHOD_NOT_ALLOWED: SharpAPIError,
+    NOT_FOUND: SharpAPIError,
+    SERVICE_UNAVAILABLE: SharpAPIError,
+    UNKNOWN_ENDPOINT: SharpAPIError,
+    UPSTREAM_ERROR: SharpAPIError,
+}
+
+# Deprecated aliases. ``bad_request`` and ``invalid_request`` were both collapsed
+# into ``validation_error`` in sharp-api-go. Kept here so that older API
+# responses (or user code still checking these strings) resolve correctly.
+# TODO: remove after 2026-10.
+DEPRECATED_CODE_ALIASES: dict[str, str] = {
+    "bad_request": VALIDATION_ERROR,
+    "invalid_request": VALIDATION_ERROR,
+}
+
+
+def canonical_code(code: str | None) -> str | None:
+    """Return the canonical code, resolving deprecated aliases."""
+    if code is None:
+        return None
+    return DEPRECATED_CODE_ALIASES.get(code, code)