Skip to content

Error Handling

The client provides specific exception types for different error conditions. All exceptions inherit from APIError, so you can catch broad or narrow depending on your needs.

Exception Hierarchy

Every API error maps to a specific exception class based on the HTTP status code:

Exception HTTP Status Description
APIError - Base class for all API errors
AuthenticationError 401 Invalid or missing API key
AuthorizationError 403 Insufficient permissions
NotFoundError 404 Resource not found
ValidationError 400 Server-side validation failed
RequestValidationError - Client-side validation failed
ConflictError 409 Resource conflict (e.g., duplicate ID, in-flight idempotency key, concurrent trait value change)
UnprocessableEntityError 422 Well-formed request that cannot be processed (has .code)
RateLimitError 429 Rate limit exceeded, or too many failed authentication attempts
ServerError 5xx Server-side error

The code Property

APIError exposes a code property that carries a machine-readable string identifying the specific failure. Not every error includes a code; check for None before branching on it.

The identity endpoints set code on every error they return. Known codes:

code Exception Meaning
TOKEN_VERIFICATION_FAILED UnprocessableEntityError The provider rejected the credential; ask the user to sign in again
EMAIL_REQUIRED UnprocessableEntityError A new user cannot be created because the provider sent no email
IDENTITY_ALREADY_LINKED ConflictError The identity belongs to another user or the user already has one
IDENTITY_NOT_LINKED NotFoundError The user has no identity from the provider being unlinked
LAST_IDENTITY ConflictError Cannot unlink the user's only remaining identity
PROVIDER_UNAVAILABLE ServerError The provider could not be reached
from vclient.exceptions import ConflictError, UnprocessableEntityError

try:
    result = await svc.identify(provider="apple", token=token)
except UnprocessableEntityError as e:
    if e.code == "TOKEN_VERIFICATION_FAILED":
        ...  # ask the user to sign in again
    elif e.code == "EMAIL_REQUIRED":
        result = await svc.identify(provider="apple", token=token, email=collected_email)
except ConflictError as e:
    if e.code == "IDENTITY_ALREADY_LINKED":
        ...  # inform the user that this provider account is already in use

Conflicts

ConflictError has these extra properties:

Property Type Description
retry_after int \| None Seconds from the Retry-After header, or None if the header is absent
is_idempotency_in_progress bool True when code == "IDEMPOTENCY_IN_PROGRESS"

The IDEMPOTENCY_IN_PROGRESS code means the API is still processing an earlier request with the same Idempotency-Key. The client handles it for you. A request that carries an idempotency key, passed by you or added by auto_idempotency_keys, waits for Retry-After (or backs off exponentially) and retries with the same key. This uses max_retries and needs auto_retry_rate_limit on. When the retries run out, the client raises the last ConflictError. Without an idempotency key, the in-progress 409 raises at once. Any other 409 also raises at once.

A same-key retry after the original request finished replays the original response, so it does not raise. If a ConflictError with is_idempotency_in_progress remains after retries run out, the outcome is unknown: the original may still be running or may fail. Refetch the resource to check, or retry later with the same key. Never treat it as success.

Restoring an archived user with the global admin update_user(user_id, is_archived=False) also returns 409 when another active user in the same company holds one of the restored user's provider identities. The detail names the provider.

Request Too Large

The API returns 413 when a request body exceeds its size limit. The client raises the base APIError for it, with no subclass. See the API documentation for the limit.

The instance Property

.instance is the request path only. It has no scheme, host, or query string.

Example

Catch specific exceptions to handle different failure modes:

from vclient import companies_service
from vclient.exceptions import (
    APIError,
    AuthenticationError,
    AuthorizationError,
    ConflictError,
    NotFoundError,
    RateLimitError,
    RequestValidationError,
    ServerError,
    UnprocessableEntityError,
    ValidationError,
)

companies = companies_service()

try:
    company = await companies.get("invalid-id")
except NotFoundError:
    print("Company not found")
except AuthorizationError:
    print("You don't have access to this company")
except AuthenticationError:
    print("Invalid API key")
except ValidationError as e:
    print(f"Server validation failed: {e}")
except RequestValidationError as e:
    print(f"Client validation failed: {e}")
except ConflictError:
    print("Conflict: reused idempotency key, or trait changed (refetch and retry)")
except UnprocessableEntityError as e:
    print(f"Cannot process request: {e.code}")
except RateLimitError as e:
    print(f"Rate limited, retry after {e.retry_after}s")
except ServerError:
    print("Server error, try again later")
except APIError as e:
    print(f"API error: {e}")

Tip

Catch APIError as a fallback to handle any unexpected API error. Place it last in your except chain so more specific exceptions are matched first.

Repeated authentication failures

After 20 requests with an invalid API key from one address within 5 minutes, the API answers requests from that address with 429 until the 5-minute window ends. A key that authenticated within the last minute keeps working. The client waits out the Retry-After time once, and the next attempt then fails with AuthenticationError. Fix the API key instead of retrying an AuthenticationError in a loop.