Error handling

Both SDKs raise typed errors so you can branch on cause. Every error carries a short code and, when applicable, an HTTP status_code.

Python

The Python SDK exposes a full exception hierarchy under toothfairyai.errors. All errors derive from ToothFairyError.

from toothfairyai import ToothFairyClient
from toothfairyai.errors import ApiError, NetworkError, ToothFairyError

try:
    agent = client.agents.create(label="…", mode="retriever", ...)
except ApiError as e:
    # HTTP error from the API
    print(e.status_code, e.response)   # e.g. 400, {"message": "..."}
except NetworkError as e:
    # connection / timeout
    print("network:", e)
except ToothFairyError as e:
    # anything else from the SDK
    print(e.code, e)

Exception	code	Raised when
ToothFairyError	UNKNOWN_ERROR	Base class; uncategorised SDK errors.
MissingApiKeyError	MISSING_API_KEY	api_key not supplied to the client.
MissingWorkspaceIdError	MISSING_WORKSPACE_ID	workspace_id not supplied to the client.
ApiError	API_ERROR	The API returned a non-2xx response. Carries status_code + response.
NetworkError	NETWORK_ERROR	Connection error or request timeout.
ValidationError	VALIDATION_ERROR	Client-side input validation failed.
StreamError	STREAM_ERROR	A streaming session failed.
JsonDecodeError	JSON_DECODE_ERROR	An SSE/data payload could not be parsed.
FileSizeError	FILE_SIZE_ERROR	An uploaded file exceeds the max size (default 15 MB).
FileNotFoundError	FILE_NOT_FOUND	A local file passed to an upload helper does not exist.

ToothFairyError attributes: message, code, status_code (optional), response (optional — the parsed API body).

Node.js

The Node.js SDK throws a single ToothFairyError class (from @toothfairyai/sdk) with code and status_code properties.

import { ToothFairyClient, ToothFairyError } from "@toothfairyai/sdk";

try {
  const agent = await client.agents.create({ label: "…", mode: "retriever", ... });
} catch (e) {
  const err = e as ToothFairyError;
  console.log(err.code, err.statusCode, err.message);
}

code	Raised when
MISSING_API_KEY	apiKey not supplied to the client.
MISSING_WORKSPACE_ID	workspaceId not supplied to the client.
API_ERROR	The API returned a non-2xx response. Carries statusCode + the response body.
NETWORK_ERROR	A network/connection error occurred (no response received).
UNKNOWN_ERROR	Any other failure.

Retries

Neither SDK retries automatically. For transient NETWORK_ERROR / 5xx API_ERROR, wrap calls in your own retry loop with backoff. The client's testConnection() / test_connection() helper already retries internally because an unbounded list probe can 502 on cold starts.