Error Handling

Comprehensive guide to error handling in HFortix.

Note

This page is a work in progress — it covers the essentials but is not yet a complete reference.

Overview

HFortix provides configurable error handling with three modes:

  • raise (default) - Raise exceptions

  • return - Return error dict

  • print - Print errors and continue

Quick Example

from hfortix import FortiOS, APIError, DuplicateEntryError

fgt = FortiOS(host='192.168.1.99', token='token')

# Default: raise exceptions
try:
    fgt.api.cmdb.firewall.address.post(name='test', subnet='10.0.0.1/32')
except DuplicateEntryError:
    print("Address already exists!")
except APIError as e:
    print(f"Error: {e.message}")

# Return error dict (error_mode parameter)
fgt_return = FortiOS(host='192.168.1.99', token='token', error_mode='return')
result = fgt_return.api.cmdb.firewall.policy.post(
    name='test',
    srcintf=[{"name": "internal"}],
    dstintf=[{"name": "wan1"}],
    srcaddr=[{"name": "all"}],
    dstaddr=[{"name": "all"}],
    service=[{"name": "ALL"}],
    action="accept"
)
if result.get('error'):
    print(f"Error: {result['error']}")

Exception Hierarchy

All exceptions come from hfortix_core.exceptions (also re-exported by hfortix_fortios and hfortix). The split is RetryableError vs NonRetryableError under APIError, under the root FortinetError.

from hfortix_core.exceptions import (
    FortinetError,          # Root of the hierarchy
    APIError,               # Base for API errors
    ResourceNotFoundError,  # 404 / object missing
    DuplicateEntryError,    # Object already exists (FortiOS -5)
    EntryInUseError,        # Object referenced elsewhere (FortiOS -23)
    InvalidValueError,      # Invalid field value (FortiOS -651)
    AuthenticationError,    # Invalid credentials
    AuthorizationError,     # Insufficient permissions
)

Warning

AuthenticationError and AuthorizationError inherit from FortinetError directly, not from APIError — an except APIError block will not catch them.

See Also