Error handling
Handle rate limits, unsupported features, and other errors from adapters.
The SDK provides typed error classes for common failure scenarios. All errors are importable from the chat package.
import { ChatError, RateLimitError, NotImplementedError, LockError } from "chat";Error types
ChatError
Base error class for all SDK errors. Every error below extends ChatError.
Prop
Type
RateLimitError
Thrown when a platform API returns a 429 response. The retryAfterMs property tells you how long to wait before retrying.
import { RateLimitError } from "chat";
try {
await thread.post("Hello!");
} catch (error) {
if (error instanceof RateLimitError) {
console.log(`Rate limited, retry after ${error.retryAfterMs}ms`);
}
}Prop
Type
NotImplementedError
Thrown when you call a feature that a platform doesn't support. For example, calling addReaction() on Teams or startTyping() on Slack.
import { NotImplementedError } from "chat";
try {
await thread.addReaction(emoji.thumbs_up);
} catch (error) {
if (error instanceof NotImplementedError) {
console.log(`Feature not supported: ${error.feature}`);
}
}Prop
Type
See the feature matrix for which features are supported on each platform.
LockError
Thrown when the SDK fails to acquire a distributed lock on a thread (used to prevent concurrent processing of messages in the same thread).
Prop
Type
Adapter errors
Adapters also throw specialized errors from the @chat-adapter/shared package:
| Error | Code | Description |
|---|---|---|
AdapterRateLimitError | RATE_LIMITED | Platform rate limit hit, includes retryAfter in seconds |
AuthenticationError | AUTH_FAILED | Invalid or expired credentials |
ResourceNotFoundError | NOT_FOUND | Requested resource (channel, message) doesn't exist |
PermissionError | PERMISSION_DENIED | Bot lacks required permissions/scopes |
ValidationError | VALIDATION_ERROR | Invalid input data (e.g. message too long) |
NetworkError | NETWORK_ERROR | Connectivity issue with platform API |
Catching errors
Use instanceof to handle specific error types:
import { RateLimitError, NotImplementedError } from "chat";
bot.onNewMention(async (thread, message) => {
try {
await thread.post("Processing...");
await thread.addReaction(emoji.eyes);
} catch (error) {
if (error instanceof RateLimitError) {
// Wait and retry
await new Promise((r) => setTimeout(r, error.retryAfterMs ?? 5000));
await thread.post("Processing...");
} else if (error instanceof NotImplementedError) {
// Skip unsupported features gracefully
} else {
throw error;
}
}
});