Error Handling

SdkError Class

The SDK uniformly uses SdkError to throw business errors:

import { SdkError } from '@atomm-developer/generator-sdk'
// CDN: const SdkError = GeneratorSDK.SdkError

try {
  await sdk.credits.consume({ amount: 10, action: 'ai_enhance' })
} catch (err) {
  if (err instanceof SdkError) {
    console.log(err.code)    // Business error code (number)
    console.log(err.message) // Error message (string)
    console.log(err.name)    // 'SdkError'
  }
}

Error Code Table

code	Description	Trigger Scenario
20101	Not logged in / Invalid token	Any API call requiring login; SDK automatically triggers logout and clears token
40301	Insufficient credits	Insufficient balance during credits.consume() or withBilling()
40302	Action not authorized	The action for credits.consume() was not applied for in the console
-1	Network error / Client error	Network disconnected, canvas export failed, provider not registered, etc.
Others	Backend business error codes	Pass-through of backend { code: xxx, msg: 'xxx' }

Error Handling Best Practices

async function safeOperation() {
  try {
    await sdk.cloud.save({ snapshot: getState(), cover: canvas })
  } catch (err) {
    if (!(err instanceof SdkError)) throw err

    switch (err.code) {
      case 20101:
        // Token expired; SDK has automatically cleared status, guide user to re-login
        await sdk.auth.login()
        break
      case 40301:
        // Insufficient credits
        showInsufficientCreditsDialog()
        break
      case -1:
        // Network error
        showNetworkErrorToast()
        break
      default:
        console.error('Unknown error:', err.code, err.message)
    }
  }
}

HTTP Interceptor Behavior

• Request Interceptor: Automatically injects uToken and lang headers.
• Response Interceptor:
  • code === 0 → Extracts and returns the data field.
  • code === 20101 → Clears token + triggers onTokenExpired callback.
  • Other codes → reject SdkError(code, msg).
  • Network error → reject SdkError(-1, 'Network error').
• Timeout: 60 seconds.