Error handling

AgentKit methods on scalekit.actions and scalekit.tools throw typed exceptions when the API returns an error. Catch the specific type first, then fall back to the base server exception.

Catch exceptions

import {
  ScalekitNotFoundException,
  ScalekitUnauthorizedException,
  ScalekitForbiddenException,
  ScalekitServerException,
} from '@scalekit-sdk/node'

try {
  const account = await scalekit.actions.getConnectedAccount({
    connectionName: 'gmail',
    identifier: 'user@example.com',
  })
} catch (err) {
  if (err instanceof ScalekitNotFoundException) {
    // No connected account yet — create one or send the user through OAuth
  } else if (err instanceof ScalekitUnauthorizedException) {
    // Invalid or expired client credentials / tokens
  } else if (err instanceof ScalekitForbiddenException) {
    // Caller is authenticated but not allowed for this resource
  } else if (err instanceof ScalekitServerException) {
    // Unexpected API or platform error — log status and code
    console.error(err.message)
  } else {
    throw err
  }
}

Exception types

Exception	When it is raised	Typical response
ScalekitNotFoundException	Resource does not exist (connected account, tool, config)	Create the resource or return a clear not-found to the user
ScalekitUnauthorizedException	Missing or invalid credentials	Refresh tokens or fix client ID/secret
ScalekitForbiddenException	Authenticated but not permitted	Adjust scopes, org, or role
ScalekitServerException	Base class for Scalekit HTTP/API failures	Log, retry when safe, surface a generic error

ScalekitServerException is the base type. Prefer checking subclasses first so not-found and auth failures get the right UX.

Tool execution errors

A failure during scalekit.tools.executeTool comes from one of two places, and the fix differs for each:

• The upstream provider rejected the call (Gmail, Slack, Salesforce, and so on). Scalekit raises a dedicated ScalekitTool* exception. The most common is ScalekitToolUnauthorizedException, which means the connected account’s provider token was expired or revoked — re-authorize the connected account. Do not change your client credentials.
• Scalekit rejected the call. A plain ScalekitUnauthorizedException (no tool details) means your client_id/client_secret or Scalekit token is invalid. The SDK already refreshed and retried before surfacing it, so fix the credentials.

Each tool exception subclasses its plain counterpart — ScalekitToolUnauthorizedException extends ScalekitUnauthorizedException — so catch the tool type first. Use isToolException() to detect any upstream tool failure, and read toolErrorCode, toolErrorMessage, and executionId for logging.

import {
  ScalekitToolUnauthorizedException,
  ScalekitToolRateLimitException,
  ScalekitUnauthorizedException,
  isToolException,
} from '@scalekit-sdk/node'

try {
  const result = await scalekit.tools.executeTool({
    toolName: 'gmail_send_email',
    identifier: 'user@example.com',
  })
} catch (err) {
  if (err instanceof ScalekitToolUnauthorizedException) {
    // Upstream provider rejected the token — re-authorize the connected account
  } else if (err instanceof ScalekitToolRateLimitException) {
    // Upstream provider rate limit — back off, then retry the tool call
  } else if (err instanceof ScalekitUnauthorizedException) {
    // Scalekit-side credentials are invalid — fix client ID/secret
  } else if (isToolException(err)) {
    // Any other upstream tool failure — inspect the provider's error code
    console.error(err.toolErrorCode, err.executionId)
  } else {
    throw err
  }
}

Exception	When it is raised	Typical response
ScalekitToolUnauthorizedException	Upstream provider returned 401 during tool execution	Re-authorize the connected account
ScalekitToolForbiddenException	Upstream provider returned 403 during tool execution	Add the missing provider scope, then re-authorize
ScalekitToolRateLimitException	Upstream provider returned 429 during tool execution	Back off and retry the tool call
ScalekitToolException	Any other upstream provider error during tool execution	Log toolErrorCode and executionId; surface a clear message

Related

• Connected accounts — connect accounts and execute tools
• Tool calling — list tool definitions
• Install — create the Scalekit client