When using convex agent, is there a callback like onError so i can handle the error client side? For instance when the rate limiter throws an error has limit is reached?
#Error handling
desert tartan
unreal crescentBOT
Hi @desert tartan. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:
Short answer: there isn’t a generic “onError” callback on the Agent itself, but you can and should handle errors on the client where you call your mutation/action, and the rate limiter is designed to throw a ConvexError you can detect.
Two recommended patterns from the docs:
-
Catch ConvexError in your client call sites (e.g., when starting an agent message). The Rate Limiter can be configured with throws: true, which throws a ConvexError carrying structured data (kind, name, retryAfter). You can detect and handle that on the client. [Usage; How It Works; Client-side Handling]
-
Use the helper isRateLimitError on the client when catching errors to show a user-friendly message or UI. [Client-side handling]
Example (client):
import { isRateLimitError } from "@convex-dev/rate-limiter";
// Wherever you trigger the agent request (mutation/action):
await submitQuestion({ question, threadId }).catch((e) => {
if (isRateLimitError(e)) {
// e.data.retryAfter is ms until you can retry
// e.data.name is the limit that was exceeded
// Show UI / toast, disable input, etc.
} else {
// Handle other ConvexError or unexpected errors
}
});
Why this way?
- Mutations/actions throw on failure; for actions specifically, you must handle and retry as appropriate. [Actions error handling]
- Throwing ConvexError keeps transactional guarantees for mutations and carries structured data to the client. [Application errors]