# Token Bucket Limits for OGC API Endpoints

Configuring a concrete, per-API-key token bucket for OGC API Tiles and Features so that a bounded burst is admitted, a sustained rate is capped, and a deep tile-pyramid crawl costs proportionally more tokens than a shallow overview read. This is the hands-on configuration behind the Rate Limiting Spatial API Traffic pattern inside the Federated Ownership & Routing Architecture: you attach an Envoy token-bucket filter keyed on the consumer’s API key, weight each request by its OGC API Tiles zoom level, and prove with curl that a client sees 200s while it has tokens and a clean 429 with Retry-After the moment its bucket empties. It reuses the tenant identity resolved by the API Gateway Mapping for GIS Services edge.

# Prerequisites

# Step-by-Step Implementation

Configure the bucket first, then layer zoom-weighting, then verify the 429 boundary with real requests. Each step ends with a verification command so you never advance on an unverified change.

# 1. Attach a per-API-key token bucket to the OGC API route

Define an Envoy local rate-limit filter whose descriptor is keyed on X-API-Key, so each consumer draws from its own bucket. The bucket admits a 600-token burst and refills 100 tokens every 6s for a sustained ceiling near 1000/min — matched to interactive tile reads, where isolating a bulk crawler is the goal, the same principle as Async Execution for Heavy Spatial Queries.

# ogc-tiles route with a per-consumer token bucket. Rejections emit 429, and
# the descriptor keys on X-API-Key so one crawler cannot drain another's bucket.
name: envoy.filters.http.local_ratelimit
typed_config:
  "@type": type.googleapis.com/envoy.extensions.filters.http.local_ratelimit.v3.LocalRateLimit
  stat_prefix: ogc_tiles_rl
  token_bucket:
    max_tokens: 600
    tokens_per_fill: 100
    fill_interval: 6s
  filter_enabled:  { default_value: { numerator: 100, denominator: HUNDRED } }
  filter_enforced: { default_value: { numerator: 100, denominator: HUNDRED } }
  descriptors:
    - entries:
        - key: consumer
          value: per-api-key
      token_bucket:            # per-consumer override of the default bucket
        max_tokens: 600
        tokens_per_fill: 100
        fill_interval: 6s
  status: { code: TooManyRequests }

Verify: confirm the filter loaded and the bucket is defined as committed.

curl -s localhost:15000/config_dump | \
  jq '.. | select(.stat_prefix? == "ogc_tiles_rl") | .token_bucket'
# expect max_tokens 600, tokens_per_fill 100, fill_interval 6s

# 2. Weight requests by tile-pyramid depth

A flat cost lets a deep-zoom crawl drain the same as an overview, which does not reflect backend cost. Assign a higher token cost to deeper OGC API Tiles zoom levels by matching the {z} path segment and applying a hits_addend, so a level-18 tile consumes more of the bucket than a level-6 tile.

# EnvoyFilter: charge deeper zoom levels more tokens. z >= 15 costs 4 tokens,
# z 10-14 costs 2, shallower costs the default 1 — encoding real tile cost.
rate_limits:
  - actions:
      - request_headers: { header_name: "x-api-key", descriptor_key: "consumer" }
    hits_addend:
      format: "%DYNAMIC_METADATA(envoy.lua:tile_cost)%"   # 1, 2, or 4 by zoom

-- envoy.lua: derive a token cost from the {z} segment of the OGC Tiles path.
function envoy_on_request(handle)
  local path = handle:headers():get(":path")
  local z = tonumber(path:match("/tiles/[^/]+/(%d+)/")) or 0
  local cost = 1
  if z >= 15 then cost = 4 elseif z >= 10 then cost = 2 end
  handle:streamInfo():dynamicMetadata():set("envoy.lua", "tile_cost", cost)
end

Verify: a deep-zoom request must decrement the bucket faster than a shallow one.

curl -s localhost:15000/stats | grep 'ogc_tiles_rl.*remaining_tokens'
# note the value, request one z=18 tile, then re-read: it should drop by ~4

# 3. Return a correct 429 with Retry-After on exhaustion

When the bucket empties, the client must receive 429 and a Retry-After telling it exactly how long until a token refills, so it backs off deterministically instead of hot-looping. Add the header to the rate-limited response.

# On a rate-limited response, add Retry-After = refill interval (6s) so the
# consumer waits the right amount before retrying, per the parent pattern.
response_headers_to_add:
  - append_action: OVERWRITE_IF_EXISTS_OR_ADD
    header: { key: "retry-after", value: "6" }
  - append_action: OVERWRITE_IF_EXISTS_OR_ADD
    header: { key: "x-ratelimit-policy", value: "ogc-tiles-per-key" }

Verify: drain the bucket and confirm the reject carries 429 and Retry-After.

for i in $(seq 1 700); do
  curl -s -o /dev/null -w "%{http_code}\n" \
    -H "X-API-Key: consumer-a" \
    "http://localhost:8080/tiles/WebMercatorQuad/6/20/33" ; \
done | sort | uniq -c
# expect a block of 200 then 429 once ~600 tokens are spent
curl -s -D - -o /dev/null -H "X-API-Key: consumer-a" \
  "http://localhost:8080/tiles/WebMercatorQuad/6/20/33" | grep -i 'retry-after'
# expect: retry-after: 6

# 4. Roll out and confirm per-key isolation

Apply the config and prove that draining one consumer’s bucket does not throttle another — the core fairness guarantee. A second API key must still receive 200s while the first is being rejected.

kubectl rollout restart deploy/gis-ingress-gateway -n gateway
kubectl rollout status  deploy/gis-ingress-gateway -n gateway --timeout=120s

Verify: consumer B is unaffected while consumer A is throttled.

# after consumer-a is exhausted from step 3:
curl -s -o /dev/null -w "A=%{http_code}\n" -H "X-API-Key: consumer-a" \
  "http://localhost:8080/tiles/WebMercatorQuad/6/20/33"   # expect 429
curl -s -o /dev/null -w "B=%{http_code}\n" -H "X-API-Key: consumer-b" \
  "http://localhost:8080/tiles/WebMercatorQuad/6/20/33"   # expect 200

# Configuration Reference

# Common Failure Modes & Fixes

Every consumer shares one bucket — one crawler throttles all clients. Root cause: requests arrive without X-API-Key, so the descriptor collapses to a single anonymous key. Fix: require the header at the gateway and reject unauthenticated calls before the limiter — confirm with curl -s localhost:15000/config_dump | jq '..|.descriptors? // empty'.

Deep-zoom crawl still saturates the tile backend despite a limit. Root cause: hits_addend is not wired, so every request costs 1 regardless of zoom and a level-18 crawl drains like an overview. Fix: confirm the Lua metadata is set and referenced — curl -s localhost:15000/stats | grep ogc_tiles_rl.*over_limit should climb faster under deep-zoom load.

Rejections return 503 instead of 429. Root cause: status.code is unset (defaults vary) or the limiter is failing closed on a global-store outage. Fix: set status: { code: TooManyRequests } explicitly and confirm the read route’s fail mode is fail-open for the global limiter.

429 returned but no Retry-After, so clients retry immediately. Root cause: response_headers_to_add was omitted, so consumers cannot compute a backoff and hot-loop the edge. Fix: add the retry-after header equal to fill_interval and verify with curl -s -D -.

Local limit lets far more traffic through than configured. Root cause: the limit is per-proxy and multiplies by replica count. Fix: divide max_tokens by replica count for a rough local cap, or move to the global Redis-backed rate-limit service for exact fairness.

# FAQ

# Related

• Rate Limiting Spatial API Traffic — the parent pattern this configuration implements
• API Gateway Mapping for GIS Services — the ingress that resolves the API key the bucket is keyed on
• Async Execution for Heavy Spatial Queries — isolating heavy workloads that a token bucket alone cannot absorb
• Zero-Trust Security for Spatial Endpoints — the identity control that pairs with per-key quotas
• Federated Ownership & Routing Architecture — up one level to the routing architecture overview