Rate Limiting Blueprint

Configurable request throttling with multiple scopes and algorithms to protect APIs from abuse

   
Feature rate-limiting
Category Access Control
Version 1.0.0
Tags rate-limiting, throttling, api-protection, security, ddos, abuse-prevention, middleware
YAML Source View on GitHub
JSON API rate-limiting.json

Fields

Name Type Required Label Description
rule_id text Yes Rate Limit Rule ID Validations: required
scope select Yes Scope Validations: required
endpoint text No Endpoint Pattern Validations: maxLength
algorithm select Yes Algorithm Validations: required
limit number Yes Request Limit Validations: required, min, max
window_seconds number Yes Window (seconds) Validations: required, min, max
burst_allowance number No Burst Allowance Validations: min
current_count number No Current Request Count  
remaining number No Remaining Requests  
reset_at datetime No Window Reset Time  
retry_after_seconds number No Retry After (seconds)  

Rules

  • algorithms:
    • fixed_window:
      • description: Count requests in fixed time buckets (e.g., per minute from :00 to :59)
      • reset_behavior: hard_reset
    • sliding_window:
      • description: Weighted average of current and previous window counts
      • weight_formula: previous_window_count * (1 - elapsed_ratio) + current_count
    • token_bucket:
      • description: Tokens replenish at a steady rate, requests consume tokens
      • refill_rate: limit / window_seconds
      • max_tokens: limit + burst_allowance
  • headers:
    • x_ratelimit_limit: true
    • x_ratelimit_remaining: true
    • x_ratelimit_reset: true
    • retry_after: true
  • storage:
    • backend: redis
    • fallback: in_memory
    • key_prefix: rl:
    • key_format: rl:{scope}:{identifier}:{endpoint}:{window}
  • bypass:
    • allowlist_ips:
    • allowlist_api_keys:
  • escalation:
    • warning_threshold_percent: 80
    • ban_threshold_consecutive_429s: 50
    • ban_duration_minutes: 60

Outcomes

Rate_limit_exceeded (Priority: 1) — Error: RATE_LIMIT_EXCEEDED

Given:

  • current_count (computed) gte limit

Then:

  • emit_event event: rate_limit.exceeded

Result: reject request with 429 status, Retry-After header, and rate limit headers

Burst_allowed (Priority: 2)

Given:

  • algorithm (db) eq token_bucket
  • current_count (computed) gte limit
  • current_count (computed) lt limit + burst_allowance

Then:

  • set_field target: current_count value: increment — Consume burst token
  • emit_event event: rate_limit.burst_used

Result: allow request using burst allowance and set headers

Rate_limit_warning (Priority: 3) — Error: RATE_LIMIT_CONFIG_INVALID

Given:

  • current_count (computed) gte limit * 0.8
  • current_count (computed) lt limit

Then:

  • set_field target: current_count value: increment — Increment the request counter
  • emit_event event: rate_limit.warning

Result: allow request but emit warning event for monitoring

Request_allowed (Priority: 5)

Given:

  • current_count (computed) lt limit

Then:

  • set_field target: current_count value: increment — Increment the request counter for this scope/window
  • set_field target: remaining value: limit - current_count - 1 — Calculate remaining requests for response header

Result: allow request and set rate limit response headers

Errors

Code Status Message Retry
RATE_LIMIT_EXCEEDED 429 Too many requests. Please try again later. Yes
RATE_LIMIT_CONFIG_INVALID 422 Invalid rate limit configuration No
RATE_LIMIT_STORAGE_ERROR 503 Rate limit service temporarily unavailable Yes

Events

Event Description Payload
rate_limit.exceeded Request rejected because rate limit was exceeded scope, identifier, endpoint, limit, window_seconds, ip_address, timestamp
rate_limit.warning Request count approaching the configured limit (80% threshold) scope, identifier, endpoint, current_count, limit, window_seconds
rate_limit.burst_used Request allowed using burst allowance (token bucket) scope, identifier, endpoint, burst_remaining, timestamp
rate_limit.ban_triggered Source temporarily banned after excessive consecutive 429s scope, identifier, ban_duration_minutes, consecutive_429_count, timestamp
Feature Relationship Reason
login recommended Login endpoints should have strict rate limits to prevent brute force
role-based-access optional Rate limit rules can vary by user role or API key tier
audit-logging optional Rate limit violations can be recorded in the audit trail

AGI Readiness

Goals

Reliable Rate Limiting

Configurable request throttling with multiple scopes and algorithms to protect APIs from abuse

Success Metrics:

Metric Target Measurement
unauthorized_access_rate 0% Failed authorization attempts that succeed
response_time_p95 < 500ms 95th percentile response time

Constraints:

  • security (non-negotiable): Follow OWASP security recommendations

Autonomy

Level: supervised

Human Checkpoints:

  • before making irreversible changes

Escalation Triggers:

  • error_rate > 5
  • consecutive_failures > 3

Verification

Invariants:

  • error messages never expose internal system details

Tradeoffs

Prefer Over Reason
security usability access control must enforce least-privilege principle

Safety

Action Permission Cooldown Max Auto
request_allowed autonomous - -
rate_limit_warning autonomous - -
rate_limit_exceeded autonomous - -
burst_allowed autonomous - -
UI Hints ```yaml layout: table_with_detail max_width: 1100px actions: primary: label: Create Rule type: submit secondary: label: View Metrics type: button fields_order: - scope - endpoint - algorithm - limit - window_seconds - burst_allowance accessibility: aria_live_region: true ```