eyeballdocs
Guides

Handle SDK errors

Catch normalized failures, decide whether to retry, and retain request or execution correlation.

HTTP failures and failed tools.run calls throw EyeballError.

ts
import { Eyeball, EyeballError } from "@eyeball/sdk";

const eyeball = new Eyeball({
  apiKey: process.env.EYEBALL_API_KEY!,
  baseUrl: process.env.EYEBALL_EXECUTOR_URL!,
});

try {
  await eyeball.tools.run(
    "gmail.get_email",
    { messageId: "missing_message" },
    { userId: "demo_user" },
  );
} catch (error) {
  if (error instanceof EyeballError) {
    console.log(
      error.code,
      error.retryable,
      error.retryAfter,
      error.providerDetail,
    );
  }
}

The package exports TOOL_ERROR_CODES and NormalizedToolError plus execution, tool, ID, and client option types. Only rate_limited and provider_unavailable retry by default.

ts
import {
  TOOL_ERROR_CODES,
  type NormalizedToolError,
} from "@eyeball/sdk";

const error: NormalizedToolError = {
  code: TOOL_ERROR_CODES.RATE_LIMITED,
  message: "Try again later.",
  retryable: true,
};
console.log(error);

See the generated Errors API for the class fields and serialized type, then use the complete taxonomy for remediation.