// troubleshooting

Rate limits

How the per-minute limit is counted, what a 429 looks like over REST and over MCP, and the 429s that come from a vendor rather than from superagnt_.

A 429 means wait. The call did not run, it cost nothing, and the same call works once the window resets. Back off for the number of seconds you were given, then retry.

How the limit is counted

The limit is a number of requests per minute, set by the plan. The figure for each plan is on Errors and rate limits.
The window is a fixed minute: it starts with the first request and resets 60 seconds later.
On a builder plan or the no-card trial there is one counter for the whole organization. Every API key and every MCP connection in every workspace draws from it, REST and MCP together.
On a managed plan the counter is per workspace and covers REST.
Minting more API keys or opening more MCP connections adds no throughput.

These REST routes are limited: /v1/data/*, /v1/data/agnt/*, /v1/connections/* and /v1/db/*. These are not: /v1/credits, /v1/usage, /v1/platforms and /v1/webhook-endpoints/*.

Over REST: a 429 with Retry-After

429 responsehttp

HTTP/1.1 429 Too Many Requests
Retry-After: 37

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded",
    "retryAfter": 37
  }
}

Wait retryAfter seconds (the same number is in the Retry-After header), then retry. If you are running many calls in a loop, slow the loop down rather than retrying each call as fast as it fails.

Over MCP: an offer with retry_after_seconds

On a builder plan or the trial, a tool call over the limit returns an upgrade offer as the tool result, with reason: "rate_limited" and retry_after_seconds. Its human_step says what happened: the call did not run, wait that many seconds and retry, or upgrade for a higher limit.

You do not need a person to clear it. Wait and retry. Only pass the offer on if the work genuinely needs more throughput than the plan allows, so the person can decide whether to upgrade. What the offer contains is on Plan limits and upgrade offers.

A 429 that is not ours

Some 429s come from a vendor, not from the superagnt_ limit. Raising the superagnt_ plan does not change them. Back off and retry.

Where	What you see	Whose limit
A connection (`connection_<vendor>_` tools, `/v1/connections/<vendor>/`)	`RATE_LIMITED`, `Rate limited by <vendor>. Please try again later.` Over MCP, `upstreamStatus: 429`.	Your account with that vendor.
People and company lookups (`data_agnt_*`)	`RATE_LIMITED`, `Upstream provider is rate limited`, with `retryAfter`	The upstream providers behind the lookup.
Other curated data sources	`PROVIDER_ERROR` with HTTP status 429	The upstream provider behind the source.

Support tickets have their own limit

A workspace can open up to 10 support tickets in a rolling hour, and a ticket accepts up to 30 customer messages in a rolling hour. Past that, agnt_support_ticket_create and agnt_support_ticket_reply return RATE_LIMITED. File one ticket per problem and add new facts as replies on it. See Getting help.