VB-OS Python SDK Error Handling

Exception hierarchy

All SDK exceptions inherit from VBOSError. Import them from vbos.exceptions:

from vbos.exceptions import (
    VBOSError,
    VBOSAuthenticationError,
    VBOSAuthorizationError,
    VBOSNotFoundError,
    VBOSValidationError,
    VBOSRateLimitError,
    VBOSServerError,
)

Exception	HTTP Status	Description
VBOSError	(base)	Base exception for all SDK errors
VBOSAuthenticationError	401	Invalid or missing API key
VBOSAuthorizationError	403	Insufficient permissions
VBOSNotFoundError	404	Resource does not exist
VBOSValidationError	400, 422	Request body or parameters failed validation
VBOSRateLimitError	429	Rate limit exceeded
VBOSServerError	5xx	Server-side error

Error fields

Every VBOSError instance carries structured error information:

Field	Type	Description
status_code	int	HTTP status code
error_code	str	Machine-readable error code
message	str	Human-readable error description
details	dict | None	Additional error context
request_id	str	Correlation ID for support

VBOSRateLimitError adds one extra field:

Field	Type	Description
retry_after	float | None	Seconds to wait before retrying

Catching errors

Catch specific errors

from vbos import VBOSClient
from vbos.exceptions import (
    VBOSNotFoundError,
    VBOSValidationError,
    VBOSAuthenticationError,
)

with VBOSClient(api_key="vbos_your_key_here") as client:
    try:
        result = client.verify(workload={"amount": 500})
    except VBOSAuthenticationError as e:
        print(f"Bad API key: {e.message}")
    except VBOSValidationError as e:
        print(f"Invalid request: {e.message}")
        print(f"Details: {e.details}")
    except VBOSNotFoundError as e:
        print(f"Not found: {e.message}")

Catch all SDK errors

from vbos.exceptions import VBOSError

try:
    result = client.verify(workload={"amount": 500})
except VBOSError as e:
    print(f"[{e.status_code}] {e.error_code}: {e.message}")
    print(f"Request ID: {e.request_id}")

Handle rate limits

import time
from vbos.exceptions import VBOSRateLimitError

try:
    result = client.verify(workload={"amount": 500})
except VBOSRateLimitError as e:
    if e.retry_after:
        print(f"Rate limited. Retry after {e.retry_after}s")
        time.sleep(e.retry_after)

Automatic retry behavior

The client retries transient failures automatically before raising an exception:

• Retried: HTTP 5xx responses
• Not retried: 4xx client errors (400, 401, 403, 404, 422, 429)
• Strategy: Exponential backoff with jitter
• Default: Up to 3 attempts (configurable via max_retries)

After all retries are exhausted, the corresponding exception is raised. Retries use separate sync_retry and async_retry implementations with configurable base and max delay constants.

# Disable automatic retries to handle errors immediately
client = VBOSClient(api_key="vbos_your_key_here", max_retries=0)

Using request IDs for support

Every error includes a request_id that can be referenced when contacting support:

try:
    result = client.verify(workload={"amount": 500})
except VBOSError as e:
    log.error(
        "VB-OS request failed",
        request_id=e.request_id,
        status_code=e.status_code,
        error_code=e.error_code,
    )