Exceptions

The NetBird client provides a hierarchy of exception types for precise error handling.

Exception Hierarchy

Exception
└── NetBirdAPIError
    ├── NetBirdAuthenticationError   (401)
    ├── NetBirdValidationError       (400)
    ├── NetBirdNotFoundError         (404)
    ├── NetBirdRateLimitError        (429)
    └── NetBirdServerError           (5xx)

Base Exception

class netbird.exceptions.NetBirdAPIError(message, status_code=None, response_data=None)

Bases: Exception

Base exception for all NetBird API errors.

message

Human-readable error message

status_code

HTTP status code if available

response_data

Raw response data from the API

Base exception for all NetBird API errors.

message: str

Human-readable error message.

status_code: int | None

HTTP status code, if available.

response_data: dict

Raw response data from the API.

__init__(message, status_code=None, response_data=None)

Authentication Errors

class netbird.exceptions.NetBirdAuthenticationError(message, status_code=None, response_data=None)

Bases: NetBirdAPIError

Raised when authentication fails (401 Unauthorized).

This typically indicates: - Invalid or expired API token - Missing Authorization header - Token lacks required permissions

Raised for 401 Unauthorized responses.

Common causes:

• Invalid or expired API token

• Missing Authorization header

• Token lacks required permissions

Validation Errors

class netbird.exceptions.NetBirdValidationError(message, status_code=None, response_data=None)

Bases: NetBirdAPIError

Raised when request validation fails (400 Bad Request).

This typically indicates: - Missing required parameters - Invalid parameter values - Malformed request body

Raised for 400 Bad Request responses.

Common causes:

• Missing required parameters

• Invalid parameter values

• Malformed request body

Not Found Errors

class netbird.exceptions.NetBirdNotFoundError(message, status_code=None, response_data=None)

Bases: NetBirdAPIError

Raised when a requested resource is not found (404 Not Found).

This typically indicates: - Resource ID does not exist - Resource has been deleted - Insufficient permissions to access resource

Raised for 404 Not Found responses.

Common causes:

• Resource ID does not exist

• Resource has been deleted

• Insufficient permissions to access resource

Rate Limit Errors

class netbird.exceptions.NetBirdRateLimitError(message, status_code=None, response_data=None, retry_after=None)

Bases: NetBirdAPIError

Raised when API rate limit is exceeded (429 Too Many Requests).

retry_after

Number of seconds to wait before retrying

Raised for 429 Too Many Requests responses.

retry_after: int | None

Number of seconds to wait before retrying.

__init__(message, status_code=None, response_data=None, retry_after=None)

Server Errors

class netbird.exceptions.NetBirdServerError(message, status_code=None, response_data=None)

Bases: NetBirdAPIError

Raised when the server encounters an internal error (5xx status codes).

This typically indicates: - Temporary server issues - Database connectivity problems - Internal service failures

Raised for 5xx server errors.

Common causes:

• Temporary server issues

• Database connectivity problems

• Internal service failures

Usage Example

from netbird.exceptions import (
    NetBirdAPIError,
    NetBirdAuthenticationError,
    NetBirdNotFoundError,
    NetBirdRateLimitError,
    NetBirdServerError,
    NetBirdValidationError,
)

try:
    peer = client.peers.get(peer_id)
except NetBirdNotFoundError:
    print(f"Peer {peer_id} not found")
except NetBirdAuthenticationError:
    print("Check your API token")
except NetBirdValidationError as e:
    print(f"Invalid request: {e.message}")
except NetBirdRateLimitError as e:
    if e.retry_after:
        time.sleep(e.retry_after)
except NetBirdServerError:
    print("Server error - try again later")
except NetBirdAPIError as e:
    print(f"API error ({e.status_code}): {e.message}")