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
| Exception | HTTP Status | When |
|---|---|---|
AuthenticationError | 401 | Invalid or missing API key |
RateLimitError | 429 | Too many requests (includes retry_after) |
ProviderError | 502+ | Upstream provider (e.g. fal.ai) failed |
ValidationError | 422 | Bad request parameters |
VisgateError | Other | Other API errors |
Usage
Exception Properties
All exceptions have:
| Property | Python | JavaScript | Description |
|---|---|---|---|
| Message | e.message | err.message | Error message |
| Error code | e.error_code | err.errorCode | Error code string |
| Details | e.details | err.details | Additional error details (dict/object or null) |
RateLimitError
| Property | Python | JavaScript | Description |
|---|---|---|---|
| Retry after | e.retry_after | err.retryAfter | Seconds to wait before retrying |
ProviderError
| Property | Python | JavaScript | Description |
|---|---|---|---|
| Provider | e.provider | err.provider | Provider name that failed |
ValidationError (JavaScript)
| Property | JavaScript | Description |
|---|---|---|
| Field | err.field | The field that failed validation |