Error Handling

Every failure mode is a distinct, catchable class. All of them extend CustodianError and carry statusCode, endpoint, and payload (also folded into .message).

Exception types

Error	When it is thrown
AuthenticationError	401 — API key missing, invalid, or expired. Also thrown locally when no key is configured.
NotFoundError	404 — the assistant, app, or team ID does not exist or is not accessible.
ValidationError	422 — malformed request (check model, prompt, examples, file, message).
ServerError	5xx — backend error, after retries.
APIConnectionError	Network failure or timeout, after retries.
APIResponseError	Any other non-2xx HTTP response.
CustodianError	Base class for all of the above.

Catch errors

import {
  createCustodian,
  AuthenticationError,
  NotFoundError,
  ValidationError,
  ServerError,
  APIConnectionError,
  CustodianError,
} from "@custodianlabs/sdk";

try {
  const app = await createCustodian({ model: "gpt-4o", prompt: "You are helpful." });
  const reply = await app.chat("Hello");
  console.log(reply?.response);
} catch (err) {
  if (err instanceof AuthenticationError) {
    console.error("Check your API key configuration.");
  } else if (err instanceof NotFoundError) {
    console.error("The requested Custodian Agent or app was not found.");
  } else if (err instanceof ValidationError) {
    console.error(`Bad request: ${err.message}`);
  } else if (err instanceof ServerError) {
    console.error(`Backend error (${err.statusCode}). Try again later.`);
  } else if (err instanceof APIConnectionError) {
    console.error("Could not reach the server. Check your network or base URL.");
  } else if (err instanceof CustodianError) {
    console.error(`Unexpected SDK error: ${err.message}`);
  } else {
    throw err;
  }
}

Error detail

catch (err) {
  if (err instanceof CustodianError) {
    console.log(err.statusCode); // e.g. 422
    console.log(err.endpoint);   // e.g. "/assistants"
    console.log(err.payload);    // the parsed error body
  }
}

Retry behavior

The SDK automatically retries network errors and 5xx responses with exponential backoff. It does not retry 401, 404, 422, or other 4xx errors.

Setting	Default	Where to set
timeout	30 seconds	Custodian / AgentTeam / createCustodian options
maxRetries	2 (up to 3 attempts total)	same
retryBackoff	0.25 seconds	HttpClient (advanced)

const custodian = new Custodian({
  model: "gpt-4o",
  systemPrompt: "You are helpful.",
  timeout: 60,
  maxRetries: 4,
});

// Disable retries:
new Custodian({ model: "gpt-4o", systemPrompt: "...", maxRetries: 0 });

Next steps

• Authentication
• Reference → SDK exceptions