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.

Related

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