Error Handling

The SDK raises typed exceptions for every failure mode — network errors, API errors, timeouts, and authentication failures.

Exception hierarchy

Python
TypeScript

ZabyApiError (Exception)
├── ZabyAuthError                    — 401 Unauthorized
│   └── ZabyRuntimeTokenExpiredError — Runtime JWT expired
├── ZabyPermissionError              — 403 Forbidden
│   └── ZabyRuntimeTokenExhaustedError — Runtime token max uses exceeded
├── ZabyValidationError              — 400 / 422 validation failure
├── ZabyRateLimitError               — 429 Too Many Requests
└── ZabyStreamError                  — SSE stream failure

ZabyApiError
├── ZabyAuthError                    — 401 Unauthorized
│   └── ZabyRuntimeTokenExpiredError — Runtime JWT expired
├── ZabyPermissionError              — 403 Forbidden
│   └── ZabyRuntimeTokenExhaustedError — Runtime token max uses exceeded
├── ZabyValidationError              — 400 / 422 validation failure
├── ZabyRateLimitError               — 429 Too Many Requests
└── ZabyStreamError                  — SSE stream failure

Catching errors

Python
TypeScript

from zaby import Zaby, ZabyApiError, ZabyAuthError, ZabyValidationError

async def create_agent_safely(zaby: Zaby):
    try:
        return await zaby.agents.create({...})
    except ZabyAuthError:
        print("Invalid API key")
    except ZabyValidationError as e:
        print(f"Validation error: {e.message}")
    except ZabyApiError as e:
        print(f"Error {e.status}: {e.message}")

import {
  Zaby,
  ZabyApiError,
  ZabyAuthError,
  ZabyValidationError,
} from "@zaby-ai/sdk";

async function createAgentSafely(zaby: Zaby) {
  try {
    return await zaby.agents.create({ /* ... */ });
  } catch (e) {
    if (e instanceof ZabyAuthError) {
      console.log("Invalid API key");
    } else if (e instanceof ZabyApiError && e.status === 404) {
      console.log(`Not found: ${e.message}`);
    } else if (e instanceof ZabyValidationError) {
      console.log(`Validation error: ${e.message}`);
    } else if (e instanceof ZabyApiError) {
      console.log(`Error ${e.status}: ${e.message}`);
    }
  }
}

ZabyApiError fields

status

int

HTTP status code

message

string

Human-readable summary

code

string

Machine-readable error code

request_id

string

Request identifier for support (Python)

requestId

string

Request identifier for support (TypeScript)

retry_after

int

Seconds to wait before retrying (from Retry-After header)

details

any

Full response body

Status codes

400 Bad Request

cause

string

Malformed request payload or invalid parameters

Python
TypeScript

try:
    await zaby.agents.create({})
except ZabyValidationError as e:
    assert e.status == 400

import { ZabyValidationError } from "@zaby-ai/sdk";

try {
  await zaby.agents.create({});
} catch (e) {
  if (e instanceof ZabyValidationError) {
    console.assert(e.status === 400);
  }
}

401 Unauthorized

cause

string

Missing or invalid API key / JWT

Python
TypeScript

zaby = Zaby(api_key="wrong-key")
# Raises ZabyAuthError

import { Zaby } from "@zaby-ai/sdk";

const zaby = new Zaby({ apiKey: "wrong-key" });
// Raises ZabyAuthError

403 Forbidden

cause

string

Insufficient permissions for the requested operation

Python
TypeScript

try:
    await zaby.agents.create({...})
except ZabyPermissionError as e:
    print(f"Forbidden: {e.message}")
except ZabyRuntimeTokenExhaustedError as e:
    print(f"Token exhausted: {e.message}")

try {
  await zaby.agents.create({ /* ... */ });
} catch (e) {
  if (e instanceof ZabyPermissionError) {
    console.log(`Forbidden: ${e.message}`);
  }
  if (e instanceof ZabyRuntimeTokenExhaustedError) {
    console.log(`Token exhausted: ${e.message}`);
  }
}

404 Not Found

cause

string

Resource does not exist

Python
TypeScript

try:
    await zaby.agents.create({})
except ZabyApiError as e:
    if e.status == 404:
        print(f"Resource not found: {e.message}")

import { ZabyApiError } from "@zaby-ai/sdk";

try {
  await zaby.agents.create({});
} catch (e) {
  if (e instanceof ZabyApiError && e.status === 404) {
    console.assert(e.status === 404);
  }
}

409 Conflict

cause

string

Duplicate slug or version conflict

429 Rate Limited

cause

string

Too many requests — back off and retry

Python
TypeScript

try:
    await zaby.agents.create({...})
except ZabyRateLimitError as e:
    wait = e.retry_after or 5
    print(f"Rate limited, retry after {wait}s")

try {
  await zaby.agents.create({ /* ... */ });
} catch (e) {
  if (e instanceof ZabyRateLimitError) {
    const wait = e.retryAfter ?? 5;
    console.log(`Rate limited, retry after ${wait}s`);
  }
}

Configure retries to handle 429s automatically.

5xx Server Error

cause

string

Temporary server-side failure — retry with backoff

Runtime Token Expired

cause

string

Runtime JWT has expired — generate a new token

Python
TypeScript

try:
    async for event in runtime.runs.stream(run_id):
        ...
except ZabyRuntimeTokenExpiredError:
    print("Token expired, generate a new one")

try {
  for await (const event of runtime.runs.stream(run_id)) { ... }
} catch (e) {
  if (e instanceof ZabyRuntimeTokenExpiredError) {
    console.log("Token expired, generate a new one");
  }
}

Stream Error

cause

string

SSE stream disconnected or malformed event

Python
TypeScript

try:
    async for event in runtime.runs.stream(run_id):
        ...
except ZabyStreamError as e:
    print(f"Stream error: {e.message}")

try {
  for await (const event of runtime.runs.stream(run_id)) { ... }
} catch (e) {
  if (e instanceof ZabyStreamError) {
    console.log(`Stream error: ${e.message}`);
  }
}

Error factory

Both SDKs expose a factory function that maps an error code or status to the correct exception subclass — useful when parsing raw API responses:

Python
TypeScript

from zaby import create_zaby_api_error, ZabyApiErrorInput

error = create_zaby_api_error(ZabyApiErrorInput(
    status=429,
    message="Too many requests",
    code="RATE_LIMITED",
    retry_after=5,
))
# Returns ZabyRateLimitError

import { createZabyApiError } from "@zaby-ai/sdk";

const error = createZabyApiError({
  status: 429,
  message: "Too many requests",
  code: "RATE_LIMITED",
  retryAfter: 5,
});
// Returns ZabyRateLimitError

Retry strategy

Python
TypeScript

from zaby import Zaby, ZabyGlobalConfig, RetryPolicy

zaby = Zaby(
    api_key="zaby_pk_...",
    config=ZabyGlobalConfig(retries=RetryPolicy(
        attempts=3,
        retry_methods=["GET", "HEAD", "OPTIONS"],
        retry_statuses=[429, 500, 502, 503, 504],
        backoff_ms=lambda attempt: min(100 * 2 ** attempt, 1000),
    )),
)

import { Zaby } from "@zaby-ai/sdk";

const zaby = new Zaby({
  apiKey: "zaby_pk_...",
  config: {
    retries: {
      attempts: 3,
      retryMethods: ["GET", "HEAD", "OPTIONS"],
      retryStatuses: [429, 500, 502, 503, 504],
      backoffMs: (attempt) => Math.min(100 * 2 ** attempt, 1000),
    },
  },
});

Common issues

401 Unauthorized

Ensure you’re using the right credential type:

Python
TypeScript

# Zaby uses API key
zaby = Zaby(api_key="zaby_pk_...")

# ZabyRuntime uses JWT
runtime = ZabyRuntime(token="eyJhbGciOi...")

import { Zaby } from "@zaby-ai/sdk";
import { ZabyRuntime } from "@zaby-ai/sdk/runtime";

// Zaby uses API key
const zaby = new Zaby({ apiKey: "zaby_pk_..." });

// ZabyRuntime uses JWT
const runtime = new ZabyRuntime({ token: "eyJhbGciOi..." });

404 Not Found

Verify the resource exists and has been published:

Python
TypeScript

version = await zaby.agents.publish(agent_id)  # Must publish first
deployment = await zaby.deployments.create(agent_id, {...})  # Then deploy

const version = await zaby.agents.publish(agent_id); // Must publish first
const deployment = await zaby.deployments.create(agent_id, { /* ... */ }); // Then deploy

Request timeout

Increase the timeout for long-running operations:

Python
TypeScript

zaby = Zaby(api_key="...", config=ZabyGlobalConfig(timeout_ms=120_000))

import { Zaby } from "@zaby-ai/sdk";

const zaby = new Zaby({
  apiKey: "...",
  config: { timeoutMs: 120_000 },
});

Connection refused

Verify your local server is running:

Python
TypeScript

zaby = Zaby(
    api_key="...",
    config=ZabyGlobalConfig(api_origin="http://localhost:9080"),
)

import { Zaby } from "@zaby-ai/sdk";

const zaby = new Zaby({
  apiKey: "...",
  config: { apiOrigin: "http://localhost:9080" },
});

Debugging

Enable debug logging to inspect requests and responses:

Python
TypeScript

import logging

# Enable HTTPX debug logging to see request/response details
logging.basicConfig(level=logging.DEBUG)
logging.getLogger("httpx").setLevel(logging.DEBUG)

import { ZabyApiError } from "@zaby-ai/sdk";

// Wrap calls to log ZabyApiError details
try {
  await zaby.health.check();
} catch (e) {
  if (e instanceof ZabyApiError) {
    console.error({ status: e.status, code: e.code, requestId: e.requestId, message: e.message });
  }
  throw e;
}

Testing

MockTransport for deterministic testing.

Configuration

Full configuration reference.

Getting Started

Clients

Guides

Error Handling

Error Handling

Exception hierarchy

Catching errors

ZabyApiError fields

Status codes

Error factory

Retry strategy

Common issues

Debugging

Testing

Configuration

​Error Handling

​Exception hierarchy

​Catching errors

​ZabyApiError fields

​Status codes

​Error factory

​Retry strategy

​Common issues

​Debugging

Testing

Configuration

Error Handling

Exception hierarchy

Catching errors

ZabyApiError fields

Status codes

Error factory

Retry strategy

Common issues

Debugging