Skip to main content
The SDK exposes two error surfaces:
  • Platform API calls return ApiResult<T> or throw ApiErrorException when using unwrapResult.
  • A2A task updates can include error metadata via the error extension.

​
Platform API errors

All API methods return ApiResult<T>. You can branch on result.ok or use unwrapResult and catch errors. 
import { buildApiClient, unwrapResult } from "agentstack-sdk";

const api = buildApiClient({ baseUrl: "https://your-agentstack-instance.com" });

const result = await api.readUser();
if (!result.ok) {
  console.error(result.error.type, result.error.message);
}

const user = unwrapResult(await api.readUser());

​
Error helpers

Use the guard helpers to match specific error types. 
import { isHttpError, isNetworkError, isParseError, isValidationError } from "agentstack-sdk";

try {
  await api.readUser();
} catch (error) {
  if (isHttpError(error, 401)) {
    console.error("Unauthorized");
  }

  if (isNetworkError(error)) {
    console.error("Network issue");
  }

  if (isParseError(error)) {
    console.error("Invalid JSON response");
  }

  if (isValidationError(error)) {
    console.error(error.apiError.details.issues);
  }
}

​
A2A extension errors

When tasks fail or are rejected, agents can emit an error extension payload. Read it with extractUiExtensionData and display a user facing message. 
import { errorExtension, extractUiExtensionData } from "agentstack-sdk";

const readError = extractUiExtensionData(errorExtension);
const errorMetadata = readError(event.status.message?.metadata);

if (errorMetadata) {
  console.error(errorMetadata.message ?? "Agent error");
}