Exceptions

Exception Hierarchy

All HFortix-Core exceptions inherit from FortinetError:

FortinetError
├── AuthenticationError          (HTTP 401)
├── AuthorizationError           (HTTP 403)
├── ValidationError
├── ConfigurationError
├── VDOMError
├── OperationNotSupportedError
├── ReadOnlyModeError
├── CircuitBreakerError
│   └── CircuitBreakerTimeoutError
└── APIError
    ├── RetryableError
    │   ├── RateLimitError                  (HTTP 429)
    │   │   ├── RateLimitExceededError
    │   │   ├── RateLimitQueueFullError
    │   │   └── RateLimitQueueTimeoutError
    │   ├── ServerError                     (HTTP 500)
    │   ├── ServiceUnavailableError         (HTTP 503)
    │   ├── CircuitBreakerOpenError
    │   └── TimeoutError
    └── NonRetryableError
        ├── BadRequestError                 (HTTP 400)
        ├── ResourceNotFoundError           (HTTP 404)
        ├── MethodNotAllowedError           (HTTP 405)
        ├── DuplicateEntryError             (error code -5, ...)
        ├── EntryInUseError                 (error code -23, ...)
        ├── InvalidValueError               (error code -651, ...)
        └── PermissionDeniedError           (error code -14, -37)

Warning

AuthenticationError and AuthorizationError inherit directly from FortinetError — not from APIError. An except APIError: handler will not catch authentication/authorization failures; catch them explicitly or use except FortinetError:.

All exceptions expose a message property that returns the original error message without the extra context that str(exception) may include:

from hfortix_core import APIError

try:
    ...
except APIError as e:
    print(e.message)      # original message only
    print(e)              # message plus endpoint/status/hint context

Base Exception

API Exceptions

exception hfortix_core.exceptions.RateLimitExceededError(message='Rate limit exceeded - request rejected', **kwargs)

Bases: RateLimitError

Rate limiter rejected request - limit exceeded (strategy=’raise’)

exception hfortix_core.exceptions.RateLimitQueueFullError(message='Rate limit queue is full - request rejected', **kwargs)

Bases: RateLimitError

Rate limiter queue is full - cannot queue request (queue_overflow=’raise’)

exception hfortix_core.exceptions.RateLimitQueueTimeoutError(message='Request timed out in rate limit queue', **kwargs)

Bases: RateLimitError

Request timed out waiting in rate limit queue

Configuration & Operation Exceptions

Retry & Circuit Breaker Exceptions

exception hfortix_core.exceptions.CircuitBreakerError(message='Circuit breaker error', **kwargs)

Bases: FortinetError

Base class for circuit breaker specific errors

exception hfortix_core.exceptions.CircuitBreakerTimeoutError(message='Circuit breaker test calls timed out', **kwargs)

Bases: CircuitBreakerError

Circuit breaker test calls timed out in half-open state

Helper Functions

These helpers live in the hfortix_core.exceptions module:

hfortix_core.exceptions.raise_for_status(response, endpoint=None, method=None, params=None)

Raise appropriate exception based on FortiOS API response

Parameters:

• response (dict) – API response dictionary

• endpoint (str) – Optional API endpoint for better error context

• method (str) – Optional HTTP method (GET, POST, PUT, DELETE)

• params (dict) – Optional request parameters (will be sanitized)

Raises:

APIError – If response indicates an error

Return type:

None

Examples

>>> response = {'status': 'error', 'http_status': 404, 'error': -3}
>>> raise_for_status(
...     response,
...     endpoint='/api/v2/cmdb/firewall/address',
...     method='GET'
... )
# Raises ResourceNotFoundError with helpful context and tip

hfortix_core.exceptions.is_retryable_error(error)

Check if error should trigger automatic retry

Parameters:

error (Exception) – Exception to check

Return type:

bool

Returns:

True if error is retryable, False otherwise

Example

>>> try:
...     fgt.api.cmdb.firewall.policy.get()
... except Exception as e:
...     if is_retryable_error(e):
...         time.sleep(5)
...         # retry logic here

hfortix_core.exceptions.get_retry_delay(error, attempt, base_delay=1.0, max_delay=60.0)

Calculate appropriate retry delay based on error type and attempt number

Parameters:

• error (Exception) – Exception that occurred

• attempt (int) – Retry attempt number (1, 2, 3, …)

• base_delay (float) – Base delay in seconds (default: 1.0)

• max_delay (float) – Maximum delay in seconds (default: 60.0)

Return type:

float

Returns:

Recommended delay in seconds

Example

>>> for attempt in range(1, 4):
...     try:
...         result = fgt.api.cmdb.firewall.policy.get()
...         break
...     except Exception as e:
...         if is_retryable_error(e):
...             delay = get_retry_delay(e, attempt)
...             time.sleep(delay)
...         else:
...             raise

hfortix_core.exceptions.get_error_description(error_code)

Get human-readable description for FortiOS error code

Parameters:

error_code (int) – FortiOS error code

Returns:

Error description or “Unknown error”

Return type:

str

Examples

>>> get_error_description(-5)
'A duplicate entry already exists'
>>> get_error_description(-651)
'Input value is invalid'

hfortix_core.exceptions.get_http_status_description(status_code)

Get human-readable description for HTTP status code

Parameters:

status_code (int) – HTTP status code

Returns:

Status description or “Unknown status code”

Return type:

str