corsair.ts
Error handler hierarchy
Corsair checks for error handlers in this order:- Plugin-specific error: e.g., Slack rate limit handler
- Root-level error: e.g., global rate limit handler for all integrations
- Plugin default: e.g., default Slack error handler
- Root default: default handler for all integrations
- Corsair fallback: built-in handler that fails gracefully
Plugin-level handler
Handle errors specific to a single integration.corsair.ts
Root-level handler
Handle errors across all integrations.corsair.ts
Default handler
Catch any error that doesn’t match a specific handler.DEFAULT is only ever the fallback: Corsair tries every named handler (the plugin’s first, then the root’s) before it, so a root DEFAULT with match: () => true never hides a plugin’s own RATE_LIMIT_ERROR.
corsair.ts
No handler needed
You don’t have to define any error handlers. Corsair provides sensible defaults that ensure your application fails gracefully. Start simple and add handlers as needed.corsair.ts
Retry strategies
When returning from an error handler, you can specify:maxRetries: number of retry attemptsretryStrategy:"exponential_backoff_jitter"or other strategies
Expired OAuth tokens
Corsair refreshes an OAuth token before a call when the stored one has expired. Some providers revoke a token early, so a call can still come back 401 with a token that looked valid. On a read, Corsair then refreshes the token once and makes the call again. A second 401 goes back to you. Writes aren’t retried this way: a write that makes several requests could repeat one that already went through. A plugin that refreshes after a 401 itself still gets only one refresh per call. When the provider refuses the refresh itself, the error says why:- The refresh token is gone: a 400 or 401 with
invalid_grant, another error code, or none. The user removed access or the grant expired. Corsair throwsAuthMissingErrorwithreason: 'revoked'and a reconnect link. The connection is marked unverified, and its message says “Access was revoked or has expired at the provider”. - The OAuth app’s own credentials were refused (
invalid_client,unauthorized_client,incorrect_client_credentials): Corsair throwsOAuthRefreshError(fromcorsair/core) withkind: 'client'. Reconnecting won’t help; fix the client ID and secret. - Anything else throws
OAuthRefreshErrorwithkind: 'transient': a 5xx, 408 or 429, another status such as a 403 or 404, or a refusal of the request itself (invalid_request,unsupported_grant_type,invalid_scope, even on a 400). Reconnecting won’t fix these either. Retry later, or check the plugin’s token URL and scopes if it keeps failing.
Reconnect and auth-missing
The handlers above cover errors from a connected integration. When a tenant hasn’t connected a plugin yet, or a stored token can no longer be refreshed, Corsair throws a typed error carrying the connect link instead:AuthMissingError: no usable credential for the tenant. Send them through a connect flow.reasonis'revoked'when the connection existed and the provider withdrew access; it is unset when the tenant never connected.ReconnectRequiredError: Hub reports that a stored connection went stale. Same fix: reconnect.
call. Anywhere else, read error.connectUrl and route the user there.