Every error in your Slack app is a knock at the door. The user has walked up, rang the bell, and is waiting to see what you drop in the bag. Hand them a treat, a clear message and a next step, and they come back next year. Hand them a trick, silence or dark porch, and they leave your app disappointed and empty handed.
The catch is that your app answers that door in workspaces you cannot open, across timezones, for people who rely on it to just work. That distance is exactly why good error handling pays off. It keeps the porch light on for users and it tells you what happened the moment a knock goes unanswered.
Treat error handling as a feature you design in from the start. The Slack SDKs give you the pieces to build exactly that.
Answer the door before they leave
Slack expects a response to most interactions within three seconds. Miss that window and the trick-or-treater is already walking away. And Slack considers the event delivery failed.
Acknowledge first and the window works for you. That way whatever happens next, the user sees your response instead of a dark porch.
Answering the door is as simple as using the ack() function. This lets Slack know the request was received and thus the user is updated as well. Call ack() right away before sending a message or fetching information. This way you stay within the three second response time.
When your app enters a failure condition for more than 95% of delivery attempts within 60 minutes, your app’s event subscriptions will be temporarily disabled. These conditions include exceeding that three second max mentioned above as well as any other response than a HTTP-200 (with some exceptions)
When Slack sends a request URL, your app should return a HTTP 200 Ok for each event you successfully receive. Slack will retry a failed request up to three times on a gradually increasing timetable. Don’t worry, they’ll let you know they are ringing the doorbell. With each retry, a x-slack-retry-num header is included. Just be aware that these retries also count against failure limits.
Make sure your user gets a treat
A trick is the empty bag: no response, a button that does nothing, a dark window. A treat is a clear reply, and it is the most valuable thing you can give someone when a request fails. Drop three things in the bag every time:
1. Acknowledgment – let them know the app received their request.
2. Explanation – use plain language to describe what went wrong.
3. Guidance – let them know what to do next. For example, retry, check a permission, or contact an admin.
Leave the lights on
Bolt logs to the console by default. You can use logLevel to set which level your want to use in the constructor: DEBUG, INFO, WARN, or ERROR.
// Import LogLevel from the package
const { App, LogLevel } = require('@slack/bolt');
// Log level is one of the options you can set in the constructor
const app = new App({
token,
signingSecret,
logLevel: LogLevel.DEBUG,
});
Every listener in your app receives the same logger as an argument, so you can add context from inside a handler:
app.event("team_join", async ({ client, event, logger }) => {
logger.info("Someone new just joined the team.");
try {
const result = await client.chat.postMessage({
channel: "C0123456789",
text: `Welcome to the team, <@${event.user.id}>!`,
});
logger.debug(result);
} catch (error) {
logger.error(error);
}
});
There are some things you don’t want to shine a light on. For one, you’ll want to keep tokens, signing secrets, and personal data out of your log lines. Be especially careful with DEBUG where whole API responses can appear. Make sure your visitor’s safety is ensured.
Listen for the things that go bump
A healthy endpoint keeps you in the loop. Slack tracks how reliably your endpoint responds to Events API deliveries. So keeping your success rate at or above 5% of events in any 60-minute window keeps delivery flowing.
Note that if it ever dips below that, Slack may pause event delivery until you resolve the failures and re-enable it. The Events API allows a generous ceiling, on the order of tens of thousands of deliveries per workspace per app per hour, so the number to watch is your own reliability rather than the volume cap.
Monitor your endpoint’s success rate and keep it comfortably healthy, which lets you hear a dip in the night and resolve it early. The same habits that make you answer the door first and catch stray errors are what hold that number up.
Every day is Halloween
Every pattern here comes back to one idea: you cannot see into the workspaces where your app runs, so build the app to keep you informed. Answer the door before you go looking for candy, so your message is what greets the user. Catch what you expect, keep the lights on, and listen for the bumps in the app. Use error logging to keep you and your customers safe this Halloween season and beyond.
