Governance Exceptions

The Governance SDK includes a set of custom exceptions to help you handle errors from governance operations. All exceptions are exported from air.governance.exceptions.

Exception Hierarchy

GovernanceError (Base Exception)
├── PermissionDeniedError
├── ResourceNotFoundError
└── DuplicateResourceError

---

Base Exception

GovernanceError

The base class for all governance-related errors. You can catch this exception to handle any error raised by the governance client.

Attributes:

• message (str): A human-readable error description.
• status_code (int | None): The HTTP status code from the server (if available).
• response_body (dict | None): The raw response body from the server (if available).

---

Permission & Access Errors

PermissionDeniedError

Status: 403 FORBIDDEN

Raised when the caller lacks the required RBAC role for the requested operation. For example, an ORG_VIEWER attempting to create a workspace.

ResourceNotFoundError

Status: 404 NOT FOUND

Raised when the requested resource does not exist. For example, querying an organization by an ID that has been deleted.

DuplicateResourceError

Status: 400 BAD REQUEST

Raised when attempting to create a resource that already exists. For example, creating an organization with a name that is already in use.

---

Usage Examples

1. Handling Permission Errors

This example demonstrates how to differentiate between a permission issue and a missing resource.

import asyncio
from air import AsyncAIRefinery
from air.governance.exceptions import (
    PermissionDeniedError,
    ResourceNotFoundError,
    GovernanceError,
)

client = AsyncAIRefinery(api_key="...")


async def manage_organization():
    try:
        org = await client.governance.organizations.me()
        print(f"Organization: {org.name}")

    except PermissionDeniedError as e:
        print(f"Access denied (HTTP {e.status_code}): {e}")
        print("Ensure your API key has the required RBAC role.")

    except ResourceNotFoundError as e:
        print(f"Not found (HTTP {e.status_code}): {e}")

    except GovernanceError as e:
        print(f"Governance error (HTTP {e.status_code}): {e}")
        if e.response_body:
            print(f"Server response: {e.response_body}")


if __name__ == "__main__":
    asyncio.run(manage_organization())

2. Handling Duplicate Resources

from air import AIRefinery
from air.governance.exceptions import DuplicateResourceError

client = AIRefinery(api_key="...")


def create_workspace_safely():
    try:
        workspace = client.governance.workspaces.create(
            name="ml-experiments",
            description="ML workspace",
        )
        print(f"Created workspace: {workspace.name}")

    except DuplicateResourceError as e:
        print(f"Workspace already exists: {e}")
        # List workspaces to find the existing one
        workspaces = client.governance.workspaces.list()
        for ws in workspaces:
            if ws.name == "ml-experiments":
                print(f"Found existing workspace: {ws.id}")
                break


if __name__ == "__main__":
    create_workspace_safely()