Error Handling

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

Exception hierarchy

Python
TypeScript

ZabyError
├── ZabyApiError          — API returned an error response
│   ├── ZabyAuthError     — 401 Unauthorized
│   └── ZabyNotFoundError — 404 Not Found
├── ZabyConnectionError   — Network / transport failure
└── ZabyTimeoutError      — Request exceeded timeout

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

Catching errors

Python
TypeScript

from zaby import Zaby, ZabyApiError, ZabyAuthError, ZabyNotFoundError

async def create_agent_safely(zaby: Zaby):
    try:
        return await zaby.agents.create({...})
    except ZabyAuthError:
        print("Invalid API key")
    except ZabyNotFoundError as e:
        print(f"Not found: {e.body}")
    except ZabyApiError as e:
        print(f"Error {e.status}: {e.body}")

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

body

any

Parsed JSON error body (Python)

message

string

Human-readable summary

code

string

Machine-readable error code (TypeScript)

requestId

string

Request identifier for support (TypeScript)

headers

dict

Response headers (Python)

Status codes

400 Bad Request

cause

string

Malformed request payload or invalid parameters

Python
TypeScript

try:
    await zaby.agents.create({})
except ZabyApiError 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

404 Not Found

cause

string

Resource does not exist

Python
TypeScript

try:
    await zaby.agents.get("nonexistent")
except ZabyNotFoundError as e:
    assert e.status == 404

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

try {
  await zaby.agents.get("nonexistent");
} 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

Configure retries to handle 429s automatically.

5xx Server Error

cause

string

Temporary server-side failure — retry with backoff

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
logging.basicConfig(level=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.

​Error Handling

​Exception hierarchy

​Catching errors

​ZabyApiError fields

​Status codes

​Retry strategy

​Common issues

​Debugging

Testing

Configuration

Error Handling

Exception hierarchy

Catching errors

ZabyApiError fields

Status codes

Retry strategy

Common issues

Debugging