Error Handling & Retry

Exception Hierarchy

FaosError (base)
├── FaosAPIError (HTTP errors from API)
│   └── FaosAuthError (401/403)
├── FaosTimeoutError (request timeout)
└── FaosRetryExhaustedError (all retries failed)

Handling API Errors

from faos import FaosClient
from faos.exceptions import FaosAPIError, FaosAuthError, FaosTimeoutError

client = FaosClient(api_key="faos_sk_...")

try:
    response = client.agents.invoke("analyst", {"query": "test"})
except FaosAuthError as e:
    print(f"Auth failed: {e.message}")
    # e.status_code == 401 or 403
except FaosAPIError as e:
    print(f"API error {e.status_code}: {e.message}")
    print(f"Error code: {e.error_code}")
    print(f"Request ID: {e.request_id}")
except FaosTimeoutError:
    print("Request timed out")

<PlaygroundButton code={"from faos import FaosClient\nfrom faos.exceptions import FaosAPIError, FaosAuthError, FaosTimeoutError\n\nclient = FaosClient(api_key=\"faos_sk_...\")\n\ntry:\n response = client.agents.invoke(\"analyst\", {\"query\": \"test\"})\nexcept FaosAuthError as e:\n print(f\"Auth failed: {e.message}\")\n # e.status_code == 401 or 403\nexcept FaosAPIError as e:\n print(f\"API error {e.status_code}: {e.message}\")\n print(f\"Error code: {e.error_code}\")\n print(f\"Request ID: {e.request_id}\")\nexcept FaosTimeoutError:\n print(\"Request timed out\")"} lang="python" />

Retry Configuration

The SDK retries automatically on transient failures with exponential backoff.

Default behavior:

• 3 retries
• 0.5s base delay with exponential backoff + jitter
• Retries on: network errors, HTTP 429, 500, 502, 503
• Respects Retry-After header from 429 responses

from faos import FaosClient, RetryConfig

# Custom retry config
client = FaosClient(
    api_key="faos_sk_...",
    retry=RetryConfig(
        max_retries=5,
        base_delay=1.0,
        max_delay=30.0,
        retry_on=(429, 500, 502, 503),
    ),
)

# Disable retries
client = FaosClient(api_key="faos_sk_...", max_retries=0)

<PlaygroundButton code={"from faos import FaosClient, RetryConfig\n\n# Custom retry config\nclient = FaosClient(\n api_key=\"faos_sk_...\",\n retry=RetryConfig(\n max_retries=5,\n base_delay=1.0,\n max_delay=30.0,\n retry_on=(429, 500, 502, 503),\n ),\n)\n\n# Disable retries\nclient = FaosClient(api_key=\"faos_sk_...\", max_retries=0)"} lang="python" />

Backoff Formula

delay = base_delay * (2 ^ attempt) + random_jitter(0-25%)

Capped at max_delay. If Retry-After header is present on 429 responses, the SDK uses that value instead.

Non-Retryable Errors

Status codes not in retry_on are never retried (e.g., 400, 401, 403, 404).