Rate limits and errors in Perk MCP
How the Perk MCP server rate limits tool calls per access token and per tool, and how it reports 401, 403, throttling, and backend errors — with causes, fixes, and retry guidance.
This reference explains how the Perk Model Context Protocol (MCP) server rate limits tool calls and how it reports common errors. Use it to understand why a call is delayed or rejected and what to do next.
How rate limiting works
The Perk MCP server rate limits tool calls per user and per tool name. Each tool has its own limit for a given token, so heavy use of one tool doesn't consume another tool's allowance.
Two limits apply. A soft limit delays requests that go beyond it, and a hard limit rejects requests that go beyond it. Space out bursts of calls and retry after a short wait if a call is delayed or rejected.
If the server can't resolve the caller's identity from the access token, it rejects the call. The server fails closed, so a call without a resolvable identity does not run.
Rate limits are environment-specific and subject to change. Exceeding established thresholds will result in requests being either temporarily delayed or outright rejected.
Common errors
Authentication and permission failures surface as HTTP 401 and 403 responses. Tool-level errors, such as throttling and backend failures, surface as tool errors with a human-readable message. The table below lists the common cases with the cause and the fix.
| Case | Cause | Fix |
|---|---|---|
401 | The access token is missing, expired, or malformed. | Reconnect the client to re-authorize and obtain a new access token. |
403-class | The token lacks a required scope, or your role doesn't permit the action. | Check that the client requested the required scope, and confirm your role permits the data you're querying. |
429 | The request went past the hard rate limit and the server rejected it. | Space out your calls and retry after the number of seconds the message gives. |
The server does not use formal error-code strings — errors arrive as messages your assistant can relay. Common examples:
- A rate-limit error reads "Rate limit exceeded (10 tool calls per second). Retry after N seconds."
- An unidentified-caller error reads "Unable to identify caller for rate limiting. Ensure the request is authenticated with a valid bearer token."
- Backend failures surface as a validation error (from a
400), a permission error (from a403— "You do not have permission to access this resource."), or a temporary-unavailability error (from a503).
Authentication errors
A 401 response means the access token is missing, expired, or malformed. Reconnect the client to re-authorize. The OAuth 2.0 client obtains a new access token, and the call succeeds on retry.
For the full authentication flow, see Authenticate with the Perk MCP server.
Permission errors
A 403-class response means the token lacks a required scope, or your role doesn't permit the action. Because the access token is scoped to your role and your company's active plan through role-based access control (RBAC), a client can only read what you can already access in Perk.
Check that the client requested the scope the tool needs. For the scope each tool requires, see the Perk MCP tools reference.
Request tracing
The Perk MCP server does not expose a correlation-ID response header. Request tracing is handled server-side through OpenTelemetry spans and structured logs, so there is no client-side correlation ID for you to capture.