error-broker

Classify agent errors and get a clear recovery action.

Agents hit rate limits, auth failures, timeouts, and bad JSON all the time. Most stacks treat every failure the same. error-broker maps the raw error to a category and tells you what to do next: wait and retry, or stop and escalate.

Free and open source (MIT). No account. No API key.

Why it helps

• Same rules for Cursor agents, scripts, and app code

• Useful defaults out of the box

• Optional YAML if you want custom categories or strategies

• MCP tools so agents can call it directly

• Repeat failures escalate instead of looping forever

Install (Cursor MCP)

Add this to .cursor/mcp.json or ~/.cursor/mcp.json:

{
  "mcpServers": {
    "error-broker": {
      "command": "npx",
      "args": ["-y", "github:amsultan2010/error-broker", "mcp"]
    }
  }
}

Reload Cursor. The agent gets tools like handle_error and classify_error.

If you clone this repo locally, you can point Cursor at the built CLI instead:

{
  "mcpServers": {
    "error-broker": {
      "command": "node",
      "args": ["/absolute/path/to/error-broker/dist/cli.js", "mcp"]
    }
  }
}

Install (npm)

npm i error-broker

import { handle, classifyError, createBroker } from "error-broker";

const decision = handle({
  status: 429,
  message: "Rate limit exceeded",
  context: { run_id: "job-1", tool: "openai" },
});

console.log(decision.instructions);
// RETRY [rate_limit]: wait 60s, then retry (attempt 1/3). ...

CLI

npx error-broker classify '{"status":429,"message":"Rate limit exceeded"}'
npx error-broker handle '{"status":401,"message":"Invalid API key"}'
npx error-broker categories
npx error-broker strategies

What you get back

handle returns JSON like:

{
  "category": "rate_limit",
  "action": "retry",
  "wait_seconds": 60,
  "max_attempts": 3,
  "attempt": 1,
  "should_retry": true,
  "escalate": false,
  "reason": "Rate limited. Wait, then retry.",
  "instructions": "RETRY [rate_limit]: wait 60s, then retry (attempt 1/3). Rate limited. Wait, then retry."
}

Pass the same context.run_id on later failures so attempt counting and escalation work.

Default categories

rate_limit, quota, auth, timeout, network, overloaded, context_overflow, invalid_response, not_found, tool_failure, unknown

Custom config (optional)

npx error-broker handle --config-dir ./my-config '{"status":429,"message":"slow down"}'

Put taxonomy.yaml and strategies.yaml in that folder. Examples live in defaults/.

MCP tools

• classify_error: map an error to a category

• handle_error: classify plus recovery advice

• list_categories: show taxonomy

• list_strategies: show recovery rules

• reset_attempts: clear counters for a run

SDK

The npm package is the SDK. Import it in your agent code:

import { createBroker, handle, classifyError } from "error-broker";

const broker = createBroker();
const result = broker.handle({
  status: 503,
  message: "service unavailable",
  context: { run_id: "batch-9", tool: "search" },
});

if (result.should_retry) {
  // wait result.wait_seconds, then retry your call
}

See examples/sdk-usage.mjs.

Until the package is on npm, install from GitHub:

npm i github:amsultan2010/error-broker

Development

npm install
npm test
npm run build
node dist/cli.js classify '{"status":429,"message":"rate limit"}'
node examples/sdk-usage.mjs

Cursor Marketplace

This repo is packaged as a Cursor plugin (.cursor-plugin/plugin.json + mcp.json).

Submit it at: https://cursor.com/marketplace/publish

Cursor reviews marketplace plugins manually. Use this repo URL:

https://github.com/amsultan2010/error-broker

License

MIT. See LICENSE. The MIT license is fully set up: LICENSE file in the repo root and "license": "MIT" in package.json.