errorHandler Module¶

The SDK errorHandler module registers a listener in your process over Socket.IO (/events). When a matching function fails, your callback runs in that process.

This is not the same as an Error Handler Triggers. Triggers invoke a server function on Poly and do not need a client online.

When to use which¶

Need	Prefer
Handle errors inside an app or worker you already run	This module
Always-on handling with no client connected	Error Handler Triggers
Page Slack / PagerDuty from Poly	Trigger → server function (or this module in a dedicated worker)

Delivery is at-most-once. There is no replay if your process was down.

Keep the process alive¶

The socket must stay connected. If the process exits, the handler is gone. Disconnect unregisters the handler on the server.

Path matching¶

path is a context or context.name prefix. The server matches the full contextName, a parent prefix, or a publicNamespace. prefix.

Register a handler¶

TypeScript

import { errorHandler } from "polyapi";

const off = errorHandler.on('myContext.myFunction', (error) => {
  // handle error
});

import { errorHandler } from "polyapi";

const off = errorHandler.on('myContext', (error) => {
  // handle error
});

on returns an unregister function:

off();

Python

Connect before on:

from polyapi import error_handler

await error_handler.get_client_and_connect()
await error_handler.on('myContext.myFunction', handler_function)

Whole context:

from polyapi import error_handler

await error_handler.get_client_and_connect()
await error_handler.on('myContext', handler_function)

Keep the event loop running (error_handler.start(...) or your own lifespan). Python has no per-handler unregister return; drop all handlers with:

await error_handler.unregister_all()

Error shape¶

The callback receives an error object with at least message, and often data, status, statusText. The server also enriches with environment / tenant / function / application / user ids and names when they exist.

Do not assume the three-arg Event shape (eventPayload, headersPayload, paramsPayload). That is for webhook Triggers and Jobs, not this module.

Related: Events and Triggers.