Error Handling¶

Every error the client can raise is a subclass of v2hub.VPNAPIError, so catching that alone is always sufficient:

from v2hub import (
    AsyncVPNClient,
    VPNAPIError,
    RateLimitError,
    NotFoundError,
)

async with AsyncVPNClient(base_url, token) as client:
    try:
        sub = await client.get_subscription("token123")
    except NotFoundError:
        print("Subscription not found")
    except RateLimitError as e:
        print(f"Rate limited. Retry after: {e.retry_after}")
    except VPNAPIError as e:
        if e.is_retryable:
            print(f"Retryable error: {e.recovery_hint}")
        else:
            print(f"Permanent error: {e}")

VPNAPIError¶

Base exception for all errors raised by the client. Every other exception below subclasses it (directly or transitively).

Constructor¶

Attributes and properties¶

str(exc) renders as "[status_code] message" when a status code is present, or just "message" otherwise. repr(exc) includes the class name, message, status code, and retry-after value.

Exception hierarchy¶

Any exception not listed with a specific recovery_hint above falls back to: "Contact API support if problem persists."

How errors are mapped¶

The client determines which exception type to raise from two, complementary sources, exposed as internal helper functions in v2hub.core.exceptions (not part of the public __all__, but useful to know about if you're debugging unexpected exception types):

• get_exception_for_status(status_code, message, response_data=None) — maps an HTTP status code to a typed exception, using the table below as a fallback, but preferring a more specific type if the response body contains a recognized error field.

• get_exception_for_error(message, response_data=None, status_code=None) — maps a response body's error field directly to a typed exception, independent of (or in addition to) the HTTP status code. Useful when a backend returns a structured error object without reliable status-code semantics.

• get_exception_for_exception(exc, message=None) — wraps a transport/runtime exception (e.g. from httpx) into the client's own hierarchy: exceptions whose class name contains "Timeout" become TimeoutError; those containing "Connection", "Network", "DNS", "SSLError", or "ProxyError" become NetworkError; anything else becomes a generic VPNAPIError.

In practice, a well-formed error body (with a recognized error/error_code/code/type field) always produces the most specific exception available, even if the raw HTTP status code alone would only map to a generic one — the error-type lookup takes priority over the status-code table.

The message shown on the raised exception is extracted from the response body's message, detail, error_message, or description field (in that order), falling back to the first entry of an errors list if present, and finally to a generic fallback string. A retry_after value is read from the response body the same way, when present, and attached to the exception regardless of which exception type was chosen.