Error Handling

Learn how to handle errors and debug issues in your Tode analytics implementation for Figma plugins and widgets.

Silent Failures by Design

Tode methods are designed to fail silently to avoid disrupting your plugin's functionality. This means:

Enable debug mode during development to see what's happening under the hood. This logs all tracking calls and any errors to the console.

code.ts

import { tode } from '@tode-sdk/core';
 
await tode.init({
  apiKey: 'your-api-key',
  debug: true  // Enable for development
});

With debug mode enabled, you'll see console logs for:

Tip: Disable debug mode in production to keep the console clean for your users.

code.ts

await tode.init({
  apiKey: 'your-api-key',
  debug: process.env.NODE_ENV === 'development'
});

Issue	Cause	Solution
Tracking not working	Tode not initialized	Call `init()` first in code.ts
No session data	WebSocket not connecting	Check network access settings in manifest.json
`isReady` always false	Config not received	Ensure `init()` is called after `showUI()`
Events not appearing	Network blocked	Verify allowed domains in manifest.json
Console shows `429`	Monthly event quota used up	Check usage on the dashboard; upgrade or wait for the period to reset
Console shows `403 event_types_limit_reached`	Too many distinct `actionName`s	Remove a type in plugin settings or upgrade (Plans and Limits)

Every tracking request answers with JSON. Success is 201 {"ok": true}. Errors carry an error code and a human-readable message:

Status	`error`	Meaning	What to do
`400`	`invalid_body`	A required field is missing or has the wrong type; `message` names it	Update the SDK; the adapters always send a valid body
`401`	`api_key_required`	No `X-API-Key` header	Pass `apiKey` to `init()`
`403`	`invalid_api_key`	Unknown or revoked key	Copy the key from the plugin settings; rotated keys stop working after 24 hours
`403`	`plugin_suspended`	The plugin exceeds the account's plan	Upgrade or archive other plugins
`403`	`event_types_limit_reached`	New `actionName` beyond the plan's cap; existing names still work	Remove a type or upgrade
`429`	`events_limit_reached`	Monthly quota used up	Upgrade or wait for the reset
`429`	`rate_limited`	More than 600 requests per minute from one key	Debounce bursts; `Retry-After` says when

The SDK logs these to the console and continues; your plugin never sees an exception.

Make sure your manifest.json includes the required domains:

manifest.json

{
  "networkAccess": {
    "allowedDomains": [
      "https://processing.usetode.dev",
      "wss://processing.usetode.dev"
    ]
  }
}

Missing network access is the most common cause of tracking failures.

Always check isReady before tracking to ensure Tode is initialized:

TypeScript

// In your UI code
if (isReady) {
  tode.trackAction('button_clicked');
}

If isReady is always false:

If you're still experiencing issues: