Error Handling

Exception types, error codes, and best practices for handling errors.

All exceptions extend VisgateError. The SDK provides typed exception classes so you can handle specific failure modes.

Exception Types

ExceptionHTTP StatusWhen
AuthenticationError401Invalid or missing API key
RateLimitError429Too many requests (includes retry_after)
ProviderError502+Upstream provider (e.g. fal.ai) failed
ValidationError422Bad request parameters
VisgateErrorOtherOther API errors

Usage

from visgate_sdk import Client
from visgate_sdk.exceptions import (
    AuthenticationError,
    RateLimitError,
    ProviderError,
    ValidationError,
    TimeoutError,
    VisgateError,
)
 
with Client() as client:
    try:
        result = client.generate("a sunset")
    except AuthenticationError:
        print("Check your API key")
    except RateLimitError as e:
        print(f"Slow down. Retry after {e.retry_after}s")
    except ProviderError as e:
        print(f"Provider {e.provider} failed: {e.message}")
    except TimeoutError:
        print("Request timed out")
    except VisgateError as e:
        print(f"API error [{e.error_code}]: {e.message}")

Exception Properties

All exceptions have:

PropertyPythonJavaScriptDescription
Messagee.messageerr.messageError message
Error codee.error_codeerr.errorCodeError code string
Detailse.detailserr.detailsAdditional error details (dict/object or null)

RateLimitError

PropertyPythonJavaScriptDescription
Retry aftere.retry_aftererr.retryAfterSeconds to wait before retrying

ProviderError

PropertyPythonJavaScriptDescription
Providere.providererr.providerProvider name that failed

ValidationError (JavaScript)

PropertyJavaScriptDescription
Fielderr.fieldThe field that failed validation

On this page