Fastapi Rate Limiting Integration

FastAPI Rate Limiting Integration

Trigger

Use this skill when:

• Adding rate limiting to FastAPI endpoints
• Using slowapi or similar rate limiting libraries
• Reviewing endpoint code that includes rate limiting decorators
• Debugging rate limits that appear to not be enforced

Required Procedure

1. slowapi @limiter.limit() requires request: Request parameter

WRONG:

@router.post("/chat")
@limiter.limit(settings.chat_rate_limit)
async def chat_endpoint(message: str):  # MISSING request parameter!
    ...

RIGHT:

@router.post("/chat")
@limiter.limit(settings.chat_rate_limit)
async def chat_endpoint(
    request: Request,  # MUST be present in the signature
    message: str
):
    ...

request: Request can appear at any position in the signature — it does not need to be first. The only requirement is that it is present so slowapi can extract the request object for rate limit key generation.

2. Use dependency injection for custom limiter logic

from slowapi import Limiter
from slowapi.util import get_remote_address
from starlette.requests import Request
import hmac

class WhitelistLimiter(Limiter):
    def __init__(self, default_limit: str, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.default_limit = default_limit

    def _check_request_limit(self, request, endpoint_func, in_middleware=True):
        key = request.headers.get("X-API-Key")
        if key and hmac.compare_digest(key, settings.health_check_api_key):
            return  # bypass rate limiting for whitelisted keys
        super()._check_request_limit(request, endpoint_func, in_middleware)

limiter = WhitelistLimiter(
    default_limit="30/minute",
    key_func=get_remote_address
)

Forbidden Shortcuts

• NEVER omit request: Request parameter on rate-limited endpoints
• NEVER assume rate limiting works without testing — silent failures are common
• NEVER use plain == for API key comparison in whitelist logic — use hmac.compare_digest

Common Error Signatures

Delegation Template

When delegating a task affected by this skill, include:

SKILLS: file:.opencode/skills/generated/fastapi-rate-limiting-integration/SKILL.md

Reviewer Checks

• All rate-limited endpoints have request: Request present in signature
• Request import is present (from starlette.requests import Request)
• Rate limiting tested with both authenticated and unauthenticated requests
• Whitelist logic uses hmac.compare_digest for key comparison
• Custom limiter extends slowapi.Limiter (not a plain class)

Source Knowledge IDs

• 88cf3ffd-8d47-4521-9da8-b944de1f4add — slowapi @limiter.limit() requires request: Request parameter
• 9cc8ee05-12f6-465b-bb3d-0f6358f61036 — Always verify decorator signature requirements when adding rate limiting