Skip to main content

​
Rate limits

The two environment variables apply to self-hosted deployments. The management API limit uses the first address in X-Forwarded-For, falling back to X-Real-IP.

​
429 response

Each rate-limited response carries these headers:
X-RateLimit-Reset is a Unix timestamp in seconds. The body is:
This body is the same for the management API, the MCP gateway, and the LLM gateway’s overall limiter. retryAfter is in seconds. The API does not send a Retry-After header. The SDK raises IgrisRateLimitError on 429.

​
Policy rate limits

Rate limits in policy rules apply to LLM rules only. A request over a rule’s window limit is denied with 429:
The call is logged as a policy denial. MCP tool rules can’t carry a limit; the API rejects it with 422. See Policies.

​
Request size limits

​
Error format

Management API errors are JSON with an error field:
Successful responses use { "data": ... }, and lists add meta with limit, offset, and sometimes total and nextCursor.

​
Status codes

​
Permission errors

A missing permission returns 403 and names the permission. See Roles & permissions.

​
Validation errors

The status and shape depend on the route.
  • Default validation (for example, PATCH /api/v1/members/:userId/permissions): 400 with the Zod result, { "success": false, "error": { ... } }.
  • Connections and the policy create and stats routes: 422 with { "success": false, "error": { "name": "ZodError", "message": "<JSON-encoded issues>" } }.
  • Policy rule checks (unsupported condition fields, limit on an MCP tool rule): 422 with a plain { "error": "message" }.

​
Plan errors

REST routes return a flat body with 403 when a feature isn’t on your plan:
Some older plan-gated routes return { "error": "Feature not available on your plan", "feature": "...", "currentPlan": "...", "requiredPlan": "..." } instead. Auth endpoints (inviting a member, changing a role) return 403 with a body that has only message, and message is a JSON string holding the same fields:
Parse message to read the fields. Inviting a member over the active-user cap returns plan_limit_active_users the same way, with current, limit and upgradeTo. Quota errors on REST routes (policy count, rules per policy, retention) return 403:
Starter allows 2 policies with 5 rules each by default.

​
MCP gateway errors

The MCP gateway returns JSON-RPC 2.0 errors:
The SDK raises IgrisPolicyDeniedError for policy denials.

​
LLM gateway errors

Errors produced inside the LLM gateway, such as a policy rate limit, use an OpenAI-style body:
The gateway-level rate limit (LLM_GATEWAY_GLOBAL_RATE_LIMIT_RPM) is different. It runs before the gateway and returns the plain { "error": "Too many requests", "retryAfter": 42 } body shown above.