Rate limits

drive-apig has three rate-control layers. They run at different points in the request lifecycle, so their response shapes and logs differ.

API Gateway usage plans

API keys attach to Terraform-managed usage plans. Usage-plan throttles happen before Lambda, so the service handler does not log the request and cannot add custom response fields.

Control	Scope
Throttle	Burst and steady-state rate per key
Quota	Request count over a configured period

Use this layer for key-level protection across private API methods.

Application token bucket

Handlers can apply business-keyed limits with TokenBucketRateLimiter from libs/rate-limiter.

flowchart LR
  R[Request] --> H[Handler]
  H --> RL[TokenBucketRateLimiter.useTokens]
  RL --> DDB[(ratelimits table)]
  DDB -->|exhausted| R429[429]
  DDB -->|tokens remain| OK[continue]

Item	Value
Store	DynamoDB table from `tblApiRateLimits`
Key	`service` + `consumer`
Algorithm	Token bucket with `fillRate` and `windowMillis`
Headers	`x-ratelimit-limit`, `x-ratelimit-remaining`, `x-ratelimit-reset`, `x-ratelimit-resource`

POST /leads/in/queue uses this layer when rateLimitsEnabled is 1.

yaml

custom:
  app:
    rateLimitsEnabled:
      dev: 0
      staging: 1
      prod: 0

Prod currently relies on WAF and usage plans for this route; staging exercises the in-handler limiter.

WAF

WAF rate-based rules are IP-scoped and apply before API Gateway invokes Lambda. They protect public and private routes because they do not depend on API keys.

See WAF and Error codes for response implications.