Skip to content
mcppipe

Error 429: rate limits and quota exceeded

A 429 from mcppipe means one of three unrelated limits tripped. They have different causes, different fixes, and only two of them are yours to configure. The response body tells you which.

Which one is it?

Section titled “Which one is it?”
Body containsLimitRetry-After?
"error": "ip_rate_limited"Per-IP request rate (service-wide)Yes
policy_code: "rate_limited"Your per-method or per-tool rate limitYes
"upgrade_url" and "plan"Monthly plan quotaNo

The absence of Retry-After on the quota case is meaningful: waiting a few seconds will not help, because the counter resets on your billing period, not on a timer.

ip_rate_limited — per-IP

Section titled “ip_rate_limited — per-IP”
{
  "error": "ip_rate_limited",
  "error_description": "your client has exceeded the per-IP request rate; back off and retry",
  "retry_after_seconds": 30
}

A service-wide protection, applied per client IP before anything else about the request is considered. You do not configure it and it is not related to your plan.

If you are hitting it, something is sending far more requests than an agent normally would — a retry loop with no backoff is the usual explanation. Honour the Retry-After header.

rate_limited — your own per-method or per-tool limit

Section titled “rate_limited — your own per-method or per-tool limit”
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32000,
    "message": "Rate limit reached for this tunnel",
    "data": { "policy_code": "rate_limited", "http_status": 429 }
  }
}

The underlying message is specific about what tripped and for how long:

rate limit reached for tool `expensive` (5/min); retry in 17s

The scope is either method (for example tools/call) or tool (a specific tool name). These are sliding-window limits you set yourself in Settings → Rate limits — so if this fires unexpectedly, the limit is probably lower than the traffic you actually have, not the other way round.

The response carries a Retry-After header and an x-mcppipe-error: rate_limited header.

See Tool governance.

Plan quota — monthly ceiling

Section titled “Plan quota — monthly ceiling”
{
  "error": "monthly tool-call limit reached on the free plan — upgrade to keep this tunnel serving traffic",
  "plan": "free",
  "upgrade_url": "https://app.mcppipe.dev/billing"
}

You reached your plan’s monthly ceiling. The reason is one of:

  • monthly tool-call limit reached
  • monthly data-transfer limit reached
  • quota backend unavailable

That last one is not your quota — it means mcppipe could not reach the counter store and failed closed, refusing traffic rather than serving it unmetered. It is a service-side condition; retry.

There is no overage billing. Reaching a ceiling returns this error; it never turns into an invoice you did not expect. Either upgrade or wait for the monthly counter to reset. See Billing & plans.

A tools/call that trips the quota gets the same information as a JSON-RPC envelope instead, with policy_code: "quota_exceeded", so the agent routes it to the pending request rather than treating it as a transport failure.

Not this error?

Section titled “Not this error?”
  • 402 — creating a tunnel over your plan’s tunnel cap. Different quota, different status.
  • 403 — refused by policy rather than by volume.

See also

Section titled “See also”