Exceptions

Exception Hierarchy

All HFortix-Core exceptions inherit from FortinetError:

FortinetError
├── APIError
│   ├── BadRequestError
│   ├── AuthenticationError
│   ├── AuthorizationError
│   ├── PermissionDeniedError
│   ├── ResourceNotFoundError
│   ├── MethodNotAllowedError
│   ├── DuplicateEntryError
│   ├── EntryInUseError
│   ├── InvalidValueError
│   ├── RateLimitError
│   ├── ServerError
│   └── ServiceUnavailableError
├── ValidationError
├── ConfigurationError
├── VDOMError
├── OperationNotSupportedError
├── ReadOnlyModeError
├── RetryableError
├── NonRetryableError
├── CircuitBreakerOpenError
└── TimeoutError

Base Exception

exception hfortix_core.FortinetError[source]

Bases: Exception

Base exception for all Fortinet API errors

API Exceptions

exception hfortix_core.APIError(message, http_status=None, error_code=None, response=None, endpoint=None, method=None, params=None, hint=None, request_id=None)[source]

Bases: FortinetError

Generic API error with optional metadata

message: Error message

http_status: HTTP status code (e.g., 400, 404, 500)

error_code: FortiOS internal error code (e.g., -5, -3)

response: Full API response dict

endpoint: API endpoint path (e.g., ‘/api/v2/cmdb/firewall/policy’)

method: HTTP method (GET, POST, PUT, DELETE)

params: Request parameters (sanitized)

hint: Helpful suggestion for resolving the error

request_id: Unique identifier for this request

timestamp: ISO 8601 timestamp when error occurred

exception hfortix_core.BadRequestError(message='Bad request', **kwargs)[source]

Bases: NonRetryableError

HTTP 400 - Bad Request

exception hfortix_core.AuthenticationError[source]

Bases: FortinetError

HTTP 401 - Authentication failed (invalid credentials)

exception hfortix_core.AuthorizationError[source]

Bases: FortinetError

HTTP 403 - Authorization failed (insufficient permissions)

exception hfortix_core.PermissionDeniedError(message='Permission denied. Insufficient privileges.', **kwargs)[source]

Bases: NonRetryableError

Permission denied, insufficient privileges (error code -14, -37)

exception hfortix_core.ResourceNotFoundError(message='Resource not found', **kwargs)[source]

Bases: NonRetryableError

HTTP 404 - Resource not found

suggest_recovery()[source]

Suggest how to recover from this error

Return type:: str

exception hfortix_core.MethodNotAllowedError(message='Method not allowed', **kwargs)[source]

Bases: NonRetryableError

HTTP 405 - Method not allowed

exception hfortix_core.DuplicateEntryError(message='A duplicate entry already exists', **kwargs)[source]

Bases: NonRetryableError

Duplicate entry exists (error code -5, -15, -100, etc.)

suggest_recovery()[source]

Suggest how to recover from this error

Return type:: str

exception hfortix_core.EntryInUseError(message='Entry is in use and cannot be deleted', **kwargs)[source]

Bases: NonRetryableError

Entry cannot be deleted because it’s in use (error code -23, -94, -95, etc.)

suggest_recovery()[source]

Suggest how to recover from this error

Return type:: str

exception hfortix_core.InvalidValueError(message='Input value is invalid', **kwargs)[source]

Bases: NonRetryableError

Invalid value provided (error code -651, -1, -50, etc.)

exception hfortix_core.RateLimitError(message='Rate limit exceeded', **kwargs)[source]

Bases: RetryableError

HTTP 429 - Rate limit exceeded

exception hfortix_core.ServerError(message='Internal server error', **kwargs)[source]

Bases: RetryableError

HTTP 500 - Internal server error

exception hfortix_core.ServiceUnavailableError(message='Service temporarily unavailable', **kwargs)[source]

Bases: RetryableError

HTTP 503 - Service temporarily unavailable

Configuration & Operation Exceptions

exception hfortix_core.ValidationError(message, field=None, value=None, constraint=None, valid_options=None, description=None, example=None, suggestion=None)[source]

Bases: FortinetError

Raised when payload validation fails before API call

Provides rich error context to help users fix validation issues.

Parameters:

message (str)
field (str | None)
value (Any)
constraint (str | None)
valid_options (list[str] | None)
description (str | None)
example (str | None)
suggestion (str | None)

field: The field that failed validation

value: The invalid value provided

constraint: The validation constraint that was violated

valid_options: List of valid options (for enums)

description: Field description from schema

example: Example of a valid value

suggestion: Helpful hint for fixing the error

exception hfortix_core.ConfigurationError[source]

Bases: FortinetError

Raised when FortiOS instance is misconfigured

Examples: - Both token and username/password provided - Missing required authentication - Invalid parameter combinations

exception hfortix_core.VDOMError(message, vdom)[source]

Bases: FortinetError

Raised when VDOM operation fails or VDOM doesn’t exist

Parameters:

message (str)
vdom (str)

vdom: The VDOM name that caused the error

exception hfortix_core.OperationNotSupportedError(message, operation, endpoint)[source]

Bases: FortinetError

Raised when attempting unsupported operation on endpoint

Parameters:

message (str)
operation (str)
endpoint (str)

operation: The operation that was attempted (e.g., ‘DELETE’)

endpoint: The endpoint that doesn’t support it

exception hfortix_core.ReadOnlyModeError[source]

Bases: FortinetError

Operation blocked by read-only mode

Raised when attempting POST/PUT/DELETE operations with read_only=True. This is a client-side block to prevent accidental writes in safe mode.

Retry & Circuit Breaker Exceptions

exception hfortix_core.RetryableError(message, http_status=None, error_code=None, response=None, endpoint=None, method=None, params=None, hint=None, request_id=None)[source]

Bases: APIError

Base exception for errors that should trigger automatic retry

These errors are typically transient and may succeed on retry: - Rate limiting (429) - Service unavailable (503) - Timeouts - Circuit breaker open

exception hfortix_core.NonRetryableError(message, http_status=None, error_code=None, response=None, endpoint=None, method=None, params=None, hint=None, request_id=None)[source]

Bases: APIError

Base exception for errors that should NOT be retried

These errors indicate client-side mistakes or permanent failures: - Bad request (400) - Resource not found (404) - Duplicate entry - Entry in use - Permission denied

exception hfortix_core.CircuitBreakerOpenError(message='Circuit breaker is open', **kwargs)[source]

Bases: RetryableError

Circuit breaker is open - service appears to be down

exception hfortix_core.TimeoutError(message='Request timed out', **kwargs)[source]

Bases: RetryableError

Request timed out