Set request limits where the cost begins
A sign-in attempt, message or expensive operation needs a request budget suited to its purpose. Wildo supports declared time windows, enforced through shared counters and keyed by the address or authenticated subject appropriate to the endpoint.
HTTP callers receive quota and retry information. The policy belongs to the operation’s owner: the framework supplies enforcement, while you decide what usage is reasonable and which identity should share a budget.
Example — Limit repeated requests for one account
A controller resolves the authenticated account and uses that identity for its request budget. Requests from different addresses then contribute to the same account bucket, instead of gaining another allowance simply by changing address.
For engineers
Use a policy, not a separate counter implementation
Resource variants can declare rateLimit. Custom HTTP controllers call checkPolicy, and headerless authenticated flows can use checkPolicyForSubject. These share the policy-window evaluator.
This illustrative custom-controller call assumes rateLimitService is injected, req and res are the current Express request/response, and authenticatedUserId and organizationId come from verified server context. The authored values describe a sample policy, not a global default.
await rateLimitService.checkPolicy(
req,
res,
{ requestsPerMinute: 10, requestsPerHour: 100 },
'example:account-action',
organizationId,
authenticatedUserId,
);
The final argument replaces the default address-derived identity. Never take that value from an untrusted request field. The namespace separates this action from other policies; organization scope separates tenant counters.
Carry the declaration across execution planes
For an existing API-call resource variant, an illustrative policy fragment is:
rateLimit: {
requestsPerMinute: 10,
requestsPerHour: 100,
},
| Plane | Budget identity and scope |
|---|---|
| REST resource operation | Address-derived identity in the HTTP operation namespace |
| MCP resource tool | Resolved credential/user subject in an MCP-specific namespace |
| Agent resource tool | Resolved credential/user subject in an agent-tool namespace |
These are independent budgets, not one shared allowance across transports. Supported MCP authentication supplies a credential or user identity, which remains attached to the operation context and determines the counted subject. The declared operation policy is checked before dispatch. Internal contexts must preserve that identity contract; a defensive missing-identity branch is not a supported client configuration.
Interpret multiple windows together
The evaluator increments every configured window. The HTTP response preserves the tightest remaining quota across applicable checks. When several windows are exceeded, retry guidance reflects the latest reset needed to satisfy all of them.
| Surface | Appropriate use |
|---|---|
Resource variant rateLimit | Policy consumed by REST, MCP and agent-tool execution, with separate buckets |
checkPolicy | Custom controller with HTTP quota headers |
checkPolicyForSubject | Authenticated flow without an HTTP response object |
| Low-level counter | Specialized callers whose semantics require direct counter handling |
Understand the operating behavior
These are fixed windows over shared atomic counters, not a token bucket. A burst at a boundary can use the end of one allowance and the start of the next. Per-endpoint enforcement propagates a shared-counter failure; the broader HTTP perimeter limiter has a separate in-memory fallback policy.
Non-production rate maxima are relaxed through the shared environment policy while the real window counter remains in use. A local run therefore does not demonstrate production ceilings. Verify the actual execution plane calls the relevant policy method: an HTTP declaration alone is not proof that every alternate transport enforces it.