API Reference

This section contains the full API reference for all public classes and functions.

Client

Vairified SDK Client

Async-first client for the Vairified Partner API.

class vairified.client.Vairified[source]

Bases: object

Async client for the Vairified Partner API.

Variables:

  • api_key – Your Partner API key

  • base_url – API base URL

  • env – Environment name (production, staging, local)

Example:

async with Vairified(api_key="vair_pk_xxx") as client:
    member = await client.get_member("user_123")
    print(member.name, member.rating)

Example with staging environment:

async with Vairified(api_key="vair_pk_xxx", env="staging") as client:
    member = await client.get_member("user_123")

Note

If your API key has the “dry-run” scope, match submissions will be validated but not persisted. This is useful for testing integrations.

Parameters:
__init__(api_key=None, *, env=None, base_url=None, timeout=30.0)[source]

Initialize the Vairified client.

Parameters:

  • api_key (Optional[str] (default: None)) – Partner API key. Falls back to VAIRIFIED_API_KEY env var.

  • env (Optional[str] (default: None)) – Environment: “production” (default), “staging”, or “local”.

  • base_url (Optional[str] (default: None)) – Override API base URL. Takes precedence over env.

  • timeout (float (default: 30.0)) – Request timeout in seconds.

Raises:

ValueError – If no API key is provided.

async close()[source]

Close the HTTP client.

Return type:

None

async get_member(player_id)[source]

Get a connected member by their external ID.

Requires OAuth Connection: The player must have connected their account to your application via OAuth before you can access their data.

Parameters:

player_id (str) – External player ID (vair_mem_xxx format).

Return type:

Member

Returns:

Member object with profile and rating data.

Raises:

  • NotFoundError – If member is not found or invalid ID format.

  • ForbiddenError – If player has not connected to your app.

Example:

member = await client.get_member("vair_mem_0ABC123def456GHI789jk")
print(f"{member.name}: {member.rating}")
async search(*, name=None, city=None, state=None, country=None, zip_code=None, rating_min=None, rating_max=None, gender=None, vairified_only=False, age=None, age_min=None, age_max=None, sort_by=None, sort_order='desc', page=1, limit=20)[source]

Search for players.

Parameters:

  • name (Optional[str] (default: None)) – Name to search for (partial match).

  • city (Optional[str] (default: None)) – City filter.

  • state (Optional[str] (default: None)) – State code (e.g., “TX”, “CA”).

  • country (Optional[str] (default: None)) – Country code (e.g., “US”).

  • zip_code (Optional[str] (default: None)) – ZIP/postal code.

  • rating_min (Optional[float] (default: None)) – Minimum rating (2.0-8.0).

  • rating_max (Optional[float] (default: None)) – Maximum rating (2.0-8.0).

  • gender (Optional[str] (default: None)) – “MALE” or “FEMALE”.

  • vairified_only (bool (default: False)) – Only return verified players.

  • age (Optional[int] (default: None)) – Exact age filter.

  • age_min (Optional[int] (default: None)) – Minimum age (for range).

  • age_max (Optional[int] (default: None)) – Maximum age (for range).

  • sort_by (Optional[str] (default: None)) – Field to sort by.

  • sort_order (str (default: 'desc')) – “asc” or “desc”.

  • page (int (default: 1)) – Page number (1-indexed).

  • limit (int (default: 20)) – Results per page (max 100).

Return type:

SearchResults

Returns:

SearchResults with players and pagination info.

Example:

results = await client.search(city="Austin", rating_min=4.0)
for player in results:
    print(f"{player.name}: {player.rating}")

# Pagination
if results.has_more:
    next_results = await results.next_page()
async find_player(name)[source]

Find a single player by name.

Convenience method that returns the first match.

Parameters:

name (str) – Player name to search for.

Return type:

Optional[Player]

Returns:

Player if found, None otherwise.

async submit_match(match)[source]

Submit a single match.

Parameters:

match (Match) – Match object with teams and scores.

Return type:

MatchResult

Returns:

MatchResult with submission status.

Raises:

VairifiedError – If submission fails.

Example:

match = Match(
    event="Weekly League",
    bracket="4.0 Doubles",
    date=datetime.now(),
    team1=("player1_id", "player2_id"),
    team2=("player3_id", "player4_id"),
    scores=[(11, 9), (11, 7)],
)
result = await client.submit_match(match)
if result:
    print(f"Submitted {result.num_games} games")
async submit_matches(matches)[source]

Submit multiple matches in a batch.

Parameters:

matches (list[Match]) – List of Match objects.

Return type:

MatchResult

Returns:

MatchResult with success, num_matches, num_games, and optionally dry_run, message, errors.

Example:

matches = [match1, match2, match3]
result = await client.submit_matches(matches)
if result:
    print(f"Submitted {result.num_games} games")
if result.dry_run:
    print("This was a dry run - no data persisted")
async get_rating_updates()[source]

Get rating updates for subscribed members.

Members are subscribed when you call get_member().

Return type:

list[RatingUpdate]

Returns:

List of RatingUpdate objects.

Example:

updates = await client.get_rating_updates()
for update in updates:
    print(f"{update.member_id}: {update.previous_rating}")
async test_webhook(webhook_url)[source]

Test webhook endpoint.

Parameters:

webhook_url (str) – URL to send test webhook to.

Return type:

dict

Returns:

Test result dict.

async start_oauth(redirect_uri, scopes=None, state=None)[source]

Start an OAuth authorization flow.

This creates a pending authorization and returns the URL where users should be redirected to approve access.

Parameters:

  • redirect_uri (str) – Your application’s callback URL.

  • scopes (Optional[list[str]] (default: None)) – Permission scopes to request. Defaults to profile:read, rating:read.

  • state (Optional[str] (default: None)) – CSRF protection state parameter (recommended).

Return type:

AuthorizationResponse

Returns:

AuthorizationResponse with the URL to redirect users to.

Raises:

OAuthError – If the authorization fails to start.

Example:

auth = await client.start_oauth(
    redirect_uri="https://myapp.com/callback",
    scopes=["profile:read", "rating:read", "match:submit"],
    state="random_csrf_token",
)
# Redirect user to auth.authorization_url
async exchange_token(code, redirect_uri)[source]

Exchange an authorization code for access and refresh tokens.

Call this after the user approves access and is redirected back to your application with a code parameter.

Parameters:

  • code (str) – Authorization code from the callback URL.

  • redirect_uri (str) – Must match the redirect_uri used in start_oauth.

Return type:

TokenResponse

Returns:

TokenResponse with access_token, refresh_token, and player_id.

Raises:

OAuthError – If the code is invalid or expired.

Example:

# After user is redirected to: https://myapp.com/callback?code=xxx
tokens = await client.exchange_token(
    code=request.query_params["code"],
    redirect_uri="https://myapp.com/callback",
)
# Store tokens.access_token and tokens.refresh_token securely
# Use tokens.player_id to identify the connected player
async refresh_access_token(refresh_token)[source]

Refresh an expired access token.

Use this when an access token expires to obtain a new one without requiring the user to re-authorize.

Parameters:

refresh_token (str) – The refresh token from a previous token exchange.

Return type:

TokenResponse

Returns:

TokenResponse with new access_token and optionally a new refresh_token.

Raises:

OAuthError – If the refresh token is invalid or revoked.

Example:

try:
    new_tokens = await client.refresh_access_token(stored_refresh_token)
    # Update stored tokens
except OAuthError as e:
    if e.error_code == "invalid_grant":
        # Refresh token revoked, user needs to re-authorize
        pass
async revoke_connection(player_id)[source]

Revoke a player’s OAuth connection.

This disconnects the player from your application. You will no longer be able to access their data or submit matches on their behalf.

Parameters:

player_id (str) – The player’s external ID (vair_mem_xxx format).

Return type:

dict

Returns:

Dict with success status.

Raises:

OAuthError – If the revocation fails.

Example:

await client.revoke_connection("vair_mem_0ABC123def456GHI789jk")
# Player is now disconnected
async get_available_scopes()[source]

Get a list of available OAuth scopes.

Return type:

list[dict[str, str]]

Returns:

List of scope objects with id, name, and description.

Example:

scopes = await client.get_available_scopes()
for scope in scopes:
    print(f"{scope['id']}: {scope['description']}")
async get_usage()[source]

Get API usage statistics for your partner account.

Return type:

dict

Returns:

Dict with usage statistics (requests, limits, etc.).

Example:

usage = await client.get_usage()
print(f"Requests today: {usage['requestsToday']}")
print(f"Rate limit: {usage['rateLimit']}/hour")
async get_leaderboard(*, category=None, age_bracket=None, scope=None, state=None, city=None, club_id=None, gender=None, verified_only=False, min_games=None, limit=50, offset=0, search=None)[source]

Get leaderboard data with filtering options.

Requires API Key Scope: leaderboard:read or read

Parameters:

  • category (Optional[str] (default: None)) – Rating category: “doubles”, “singles”, “mixed” (default: doubles).

  • age_bracket (Optional[str] (default: None)) – Age bracket: “open”, “40+”, “50+”, “60+”, “70+” (default: open).

  • scope (Optional[str] (default: None)) – Geographic scope: “global”, “state”, “city”, “club” (default: global).

  • state (Optional[str] (default: None)) – State code (required if scope is “state”).

  • city (Optional[str] (default: None)) – City name (required if scope is “city”).

  • club_id (Optional[str] (default: None)) – Club ID (required if scope is “club”).

  • gender (Optional[str] (default: None)) – Filter by gender: “male”, “female”.

  • verified_only (bool (default: False)) – Only show VAIRified players.

  • min_games (Optional[int] (default: None)) – Minimum games to appear (default: 10).

  • limit (int (default: 50)) – Results per page (default: 50, max: 100).

  • offset (int (default: 0)) – Pagination offset.

  • search (Optional[str] (default: None)) – Search by player name.

Return type:

dict

Returns:

Dict with players, stats, filters, and pagination.

Example:

# Get global doubles leaderboard
leaderboard = await client.get_leaderboard()

# Get state-level singles leaderboard
tx_leaderboard = await client.get_leaderboard(
    category="singles",
    scope="state",
    state="TX",
)

# Get 50+ age bracket
senior_leaderboard = await client.get_leaderboard(
    age_bracket="50+",
    verified_only=True,
)

for player in leaderboard["players"]:
    print(f"#{player['rank']} {player['displayName']}: {player['rating']}")
async get_player_rank(player_id, *, category='doubles', age_bracket='open', scope='global', state=None, city=None, club_id=None, context_size=5)[source]

Get a specific player’s rank on the leaderboard.

Requires API Key Scope: leaderboard:read or read

Parameters:

  • player_id (str) – External player ID (vair_mem_xxx format).

  • category (str (default: 'doubles')) – Rating category (default: “doubles”).

  • age_bracket (str (default: 'open')) – Age bracket (default: “open”).

  • scope (str (default: 'global')) – Geographic scope (default: “global”).

  • state (Optional[str] (default: None)) – State code for state scope.

  • city (Optional[str] (default: None)) – City name for city scope.

  • club_id (Optional[str] (default: None)) – Club ID for club scope.

  • context_size (int (default: 5)) – Number of nearby players to include (default: 5).

Return type:

dict

Returns:

Dict with rank, percentile, and nearby players.

Example:

rank = await client.get_player_rank(
    "vair_mem_xxx",
    category="doubles",
    context_size=5,
)

print(f"Rank: #{rank['rank']} (top {rank['percentile']}%)")
print(f"Points to next rank: {rank.get('pointsToNextRank')}")

# Show nearby players
for nearby in rank["nearbyPlayers"]:
    print(f"#{nearby['rank']} {nearby['displayName']}")
async get_leaderboard_categories()[source]

Get available leaderboard categories and brackets.

Requires API Key Scope: leaderboard:read or read

Return type:

dict

Returns:

Dict with categories, ageBrackets, and scopes.

Example:

categories = await client.get_leaderboard_categories()

print("Categories:", [c["name"] for c in categories["categories"]])
print("Age Brackets:", [b["name"] for b in categories["ageBrackets"]])

Models

Vairified SDK Models

Rich model classes with methods for easy API interaction.

class vairified.models.RatingSplit[source]

Bases: object

A single rating split with metadata.

Variables:

  • rating – The rating value.

  • abbr – Abbreviation (e.g., “VG”, “50+”).

  • date_played – Date of last match in this category.

Parameters:
rating: float
abbr: str
date_played: str | None = None
classmethod from_dict(data)[source]

Create from API response dict.

Parameters:

data (dict) – Rating split data from API.

Return type:

RatingSplit

Returns:

RatingSplit instance.

__init__(rating, abbr, date_played=None)
Parameters:
Return type:

None

class vairified.models.RatingSplits[source]

Bases: object

Rating breakdown by category.

Access ratings by category name (e.g., “open”, “50_and_up”) or use convenience properties for common categories.

Variables:

splits – Dict mapping category names to RatingSplit objects.

Parameters:

splits (dict[str, RatingSplit] (default: <factory>))

splits: dict[str, RatingSplit]
classmethod from_dict(data)[source]

Create from API response dict.

Parameters:

data (Optional[dict]) – Rating splits data from API (nested or flat format).

Return type:

RatingSplits

Returns:

RatingSplits instance.

get(category)[source]

Get rating for a category.

Parameters:

category (str) – Category name (e.g., “open”, “VG”, “50_and_up”).

Return type:

Optional[float]

Returns:

Rating value or None if not found.

property open: float | None

Open division rating.

property gender: float | None

Gender-specific rating (same gender doubles).

property mixed: float | None

Mixed doubles rating.

property recreational: float | None

Recreational rating.

property singles: float | None

Singles rating.

property best: float | None

Best available verified rating.

to_dict()[source]

Convert to dict.

Return type:

dict

__init__(splits=<factory>)
Parameters:

splits (dict[str, RatingSplit] (default: <factory>))

Return type:

None

class vairified.models.Player[source]

Bases: object

A player in the Vairified system.

From public search, only limited data is available (display name, location, rating). For full profile data, use Vairified.get_member() with OAuth consent.

Variables:

  • id – External player ID (vair_mem_xxx format).

  • display_name – Display name (First Name + Last Initial from search).

  • first_name – Player’s first name (only from connected member).

  • last_name – Player’s last name (only from connected member).

  • rating – Primary/overall rating (2.0-8.0).

  • is_vairified – Whether player is verified.

  • is_connected – Whether player has connected to your app.

  • rating_splits – Ratings by category (only from connected member).

  • city – City.

  • state – State code.

  • country – Country code.

Parameters:
id: str
rating: float
display_name: str | None = None
first_name: str | None = None
last_name: str | None = None
is_vairified: bool = False
is_connected: bool = False
rating_splits: RatingSplits
city: str | None = None
state: str | None = None
country: str | None = None
property name: str

Full name (or display name if full name not available).

property verified_rating: float | None

Best verified rating.

classmethod from_dict(data, client=None)[source]

Create from API response dict.

Handles both search (limited data) and member (full data) formats.

Parameters:

  • data (dict) – Player data from API.

  • client (Optional[Vairified] (default: None)) – Vairified client for back-reference.

Return type:

Player

Returns:

Player instance.

__init__(id, rating, display_name=None, first_name=None, last_name=None, is_vairified=False, is_connected=False, rating_splits=<factory>, city=None, state=None, country=None, _client=None)
Parameters:
Return type:

None

class vairified.models.Member[source]

Bases: Player

A member with full profile access (requires OAuth connection).

Extends Player with additional profile data and methods. Only accessible for players who have connected their account via OAuth.

Variables:

  • email – Email address (only if profile:email scope granted).

  • granted_scopes – List of scopes the player granted to your app.

Parameters:
email: str | None = None
granted_scopes: list[str]
classmethod from_dict(data, client=None)[source]

Create from API response dict.

Parameters:

  • data (dict) – Member data from API.

  • client (Optional[Vairified] (default: None)) – Vairified client for back-reference.

Return type:

Member

Returns:

Member instance.

has_scope(scope)[source]

Check if the player has granted a specific scope.

Parameters:

scope (str) – Scope to check (e.g., ‘profile:email’, ‘match:submit’).

Return type:

bool

Returns:

True if scope is granted.

async refresh()[source]

Refresh member data from API.

Return type:

Member

Returns:

Updated Member instance (self).

Raises:

RuntimeError – If not connected to client.

__init__(id, rating, display_name=None, first_name=None, last_name=None, is_vairified=False, is_connected=False, rating_splits=<factory>, city=None, state=None, country=None, _client=None, email=None, granted_scopes=<factory>)
Parameters:
Return type:

None

class vairified.models.Match[source]

Bases: object

A match to submit to the Vairified Partner API.

For doubles matches, provide two player IDs per team. For singles, provide one player ID per team.

Variables:

  • event – Event/tournament name (required).

  • bracket – Bracket/division name (required).

  • date – Match date and time (required).

  • team1 – Tuple of (player1_id, player2_id) or just (player1_id,) for singles.

  • team2 – Tuple of (player1_id, player2_id) or just (player1_id,) for singles.

  • scores – List of (team1_score, team2_score) tuples for each game.

  • match_type – Match type (e.g., “SIDEOUT”, “RALLY”).

  • source – Match source (e.g., “CLUB”, “TOURNAMENT”).

  • location – Match location (optional).

  • identifier – Unique match identifier (auto-generated if not provided).

Example:

# Doubles match: 11-9, 11-7
match = Match(
    event="Weekly League",
    bracket="4.0 Doubles",
    date=datetime.now(),
    team1=("player1_id", "player2_id"),
    team2=("player3_id", "player4_id"),
    scores=[(11, 9), (11, 7)],
)

# Singles match: 11-8, 9-11, 11-6
match = Match(
    event="Club Singles",
    bracket="Open Singles",
    date=datetime.now(),
    team1=("player1_id",),
    team2=("player2_id",),
    scores=[(11, 8), (9, 11), (11, 6)],
)
Parameters:
event: str
bracket: str
date: datetime
team1: tuple[str, ...]
team2: tuple[str, ...]
scores: list[tuple[int, int]]
match_type: str = 'SIDEOUT'
source: str = 'PARTNER'
location: str | None = None
identifier: str | None = None
id: str | None = None
property format: str

Match format: SINGLES or DOUBLES.

property winner: int

Team that won (1 or 2).

Returns:

1 if team 1 won, 2 if team 2 won, 0 if tie.

property score_summary: str

Score summary like ‘11-9, 11-7’.

to_dict()[source]

Convert to API request format.

Return type:

dict[str, Any]

Returns:

Dict matching the MatchInput DTO.

__init__(event, bracket, date, team1, team2, scores, match_type='SIDEOUT', source='PARTNER', location=None, identifier=None, id=None)
Parameters:
Return type:

None

class vairified.models.RatingUpdate[source]

Bases: object

A rating change notification.

Variables:

  • id – External player ID (vair_mem_xxx format).

  • member_name – Member name.

  • previous_rating – Rating before change.

  • new_rating – Rating after change.

  • changed_at – When the change occurred.

  • rating_splits – Updated rating splits.

Parameters:
id: str
previous_rating: float
new_rating: float
changed_at: datetime
member_name: str | None = None
rating_splits: RatingSplits
property change: float

Amount of rating change.

property improved: bool

Whether rating improved.

classmethod from_dict(data, client=None)[source]

Create from API response dict.

Parameters:

  • data (dict) – Rating update data from API.

  • client (Optional[Vairified] (default: None)) – Vairified client for back-reference.

Return type:

RatingUpdate

Returns:

RatingUpdate instance.

async get_member()[source]

Fetch the member associated with this update.

Return type:

Member

Returns:

Member object.

Raises:

RuntimeError – If not connected to client.

__init__(id, previous_rating, new_rating, changed_at, member_name=None, rating_splits=<factory>, _client=None)
Parameters:
Return type:

None

class vairified.models.MatchResult[source]

Bases: object

Result of a match submission.

Variables:

  • success – Whether submission succeeded.

  • num_matches – Number of matches processed.

  • num_games – Number of games recorded.

  • dry_run – Whether this was a dry-run (validation only).

  • message – Human-readable result message.

  • errors – List of validation/processing errors.

Parameters:

  • success (bool)

  • num_matches (int)

  • num_games (int)

  • dry_run (bool (default: False))

  • message (Optional[str] (default: None))

  • errors (list[str] (default: <factory>))

success: bool
num_matches: int
num_games: int
dry_run: bool = False
message: str | None = None
errors: list[str]
classmethod from_dict(data)[source]

Create from API response dict.

Parameters:

data (dict) – Match result data from API.

Return type:

MatchResult

Returns:

MatchResult instance.

property is_dry_run: bool

Alias for dry_run.

__init__(success, num_matches, num_games, dry_run=False, message=None, errors=<factory>)
Parameters:

  • success (bool)

  • num_matches (int)

  • num_games (int)

  • dry_run (bool (default: False))

  • message (Optional[str] (default: None))

  • errors (list[str] (default: <factory>))

Return type:

None

class vairified.models.SearchResults[source]

Bases: object

Paginated search results.

Supports iteration and async pagination.

Variables:

  • players – List of Player objects.

  • total – Total matching players.

  • page – Current page number.

  • limit – Results per page.

Parameters:
players: list[Player]
total: int
page: int
limit: int
property has_more: bool

Whether more results are available.

property pages: int

Total number of pages.

async next_page()[source]

Fetch next page of results.

Return type:

SearchResults

Returns:

SearchResults for the next page.

Raises:
classmethod from_dict(data, client=None, filters=None)[source]

Create from API response dict.

Parameters:

  • data (dict) – Search results data from API.

  • client (Optional[Vairified] (default: None)) – Vairified client for back-reference.

  • filters (Optional[dict] (default: None)) – Original search filters for pagination.

Return type:

SearchResults

Returns:

SearchResults instance.

__init__(players, total, page, limit, _client=None, _filters=<factory>)
Parameters:
Return type:

None

OAuth

Vairified OAuth Helpers

Utilities for implementing the “Connect with Vairified” OAuth flow.

class vairified.oauth.OAuthConfig[source]

Bases: object

OAuth configuration for a partner application.

Variables:

  • api_key – Partner API key.

  • redirect_uri – Your application’s callback URL.

  • base_url – Vairified API base URL.

Parameters:

  • api_key (str)

  • redirect_uri (str)

  • base_url (str (default: 'https://api-next.vairified.com/api/v1'))

api_key: str
redirect_uri: str
base_url: str = 'https://api-next.vairified.com/api/v1'
__init__(api_key, redirect_uri, base_url='https://api-next.vairified.com/api/v1')
Parameters:

  • api_key (str)

  • redirect_uri (str)

  • base_url (str (default: 'https://api-next.vairified.com/api/v1'))

Return type:

None

class vairified.oauth.AuthorizationResponse[source]

Bases: object

Response from starting an OAuth authorization.

Variables:

  • authorization_url – Full URL to redirect the user to.

  • code – Authorization code (for internal tracking).

  • state – CSRF state parameter.

Parameters:
authorization_url: str
code: str
state: str | None = None
__init__(authorization_url, code, state=None)
Parameters:
Return type:

None

class vairified.oauth.TokenResponse[source]

Bases: object

Response from exchanging an authorization code for tokens.

Variables:

  • access_token – Access token for API requests.

  • refresh_token – Refresh token for obtaining new access tokens.

  • expires_in – Token expiration in seconds.

  • scope – Granted scopes.

  • player_id – Connected player’s external ID.

Parameters:
access_token: str
refresh_token: str | None
expires_in: int
scope: list[str]
player_id: str
__init__(access_token, refresh_token, expires_in, scope, player_id)
Parameters:
Return type:

None

vairified.oauth.get_authorization_url(config, scopes=None, state=None)[source]

Build the URL to redirect users to for OAuth authorization.

This is a helper for building the URL manually. In most cases, you should use the Vairified client’s OAuth methods instead.

Parameters:

  • config (OAuthConfig) – OAuth configuration.

  • scopes (Optional[list[str]] (default: None)) – Permission scopes to request.

  • state (Optional[str] (default: None)) – CSRF protection state parameter.

Return type:

str

Returns:

URL to redirect the user to.

Example:

config = OAuthConfig(
    api_key="vair_pk_xxx",
    redirect_uri="https://myapp.com/oauth/callback",
)
url = get_authorization_url(config, scopes=["profile:read", "rating:read"])
# Redirect user to this URL
vairified.oauth.validate_scope(scope)[source]

Check if a scope is valid.

Parameters:

scope (str) – Scope string to validate.

Return type:

bool

Returns:

True if scope is valid.

vairified.oauth.describe_scope(scope)[source]

Get a human-readable description of a scope.

Parameters:

scope (str) – Scope string.

Return type:

str

Returns:

Description of what the scope grants access to.

vairified.oauth.describe_scopes(scopes)[source]

Get descriptions for multiple scopes.

Parameters:

scopes (list[str]) – List of scope strings.

Return type:

list[dict[str, str]]

Returns:

List of dicts with ‘scope’ and ‘description’ keys.

Errors

Vairified SDK Errors

Custom exception classes for API errors.

exception vairified.errors.VairifiedError[source]

Bases: Exception

Base exception for Vairified API errors.

Variables:

  • message – Error message.

  • status_code – HTTP status code (if applicable).

  • response – Raw response body (if available).

Parameters:
__init__(message, status_code=None, response=None)[source]

Initialize the error.

Parameters:

  • message (str) – Human-readable error message.

  • status_code (Optional[int] (default: None)) – HTTP status code.

  • response (Optional[Any] (default: None)) – Raw response body.

exception vairified.errors.RateLimitError[source]

Bases: VairifiedError

Raised when rate limit is exceeded.

Variables:

retry_after – Seconds to wait before retrying.

Parameters:

  • message (str (default: 'Rate limit exceeded'))

  • retry_after (Optional[int] (default: None))

__init__(message='Rate limit exceeded', retry_after=None, **kwargs)[source]

Initialize rate limit error.

Parameters:

  • message (str (default: 'Rate limit exceeded')) – Error message.

  • retry_after (Optional[int] (default: None)) – Seconds to wait before retrying.

exception vairified.errors.AuthenticationError[source]

Bases: VairifiedError

Raised when authentication fails.

Typically means the API key is invalid or expired.

Parameters:

message (str (default: 'Invalid API key'))

__init__(message='Invalid API key', **kwargs)[source]

Initialize authentication error.

Parameters:

message (str (default: 'Invalid API key')) – Error message.

exception vairified.errors.NotFoundError[source]

Bases: VairifiedError

Raised when a resource is not found.

Typically means the requested member/player doesn’t exist.

Parameters:

message (str (default: 'Resource not found'))

__init__(message='Resource not found', **kwargs)[source]

Initialize not found error.

Parameters:

message (str (default: 'Resource not found')) – Error message.

exception vairified.errors.ValidationError[source]

Bases: VairifiedError

Raised when request validation fails.

Check the response body for details on which fields failed validation.

Parameters:

message (str (default: 'Validation error'))

__init__(message='Validation error', **kwargs)[source]

Initialize validation error.

Parameters:

message (str (default: 'Validation error')) – Error message.

exception vairified.errors.OAuthError[source]

Bases: VairifiedError

Raised when an OAuth operation fails.

This can occur during authorization, token exchange, refresh, or revocation.

Variables:

error_code – OAuth error code (e.g., ‘invalid_grant’, ‘expired_token’).

Parameters:

  • message (str (default: 'OAuth error'))

  • error_code (Optional[str] (default: None))

__init__(message='OAuth error', error_code=None, **kwargs)[source]

Initialize OAuth error.

Parameters:

  • message (str (default: 'OAuth error')) – Error message.

  • error_code (Optional[str] (default: None)) – OAuth error code.