Rate limits

Explain a genuine request-limit rejection while preserving 429. User identification groups synthetic clients by the X-CR-Client header and limits GET requests to exactly /demo/rate-limit.

Visitor response: Demo request limit reached

The header is a demonstration identity; callers can change it. It does not authenticate clients or define a production identity design.

Connect identification, limiter and response

Each fragment belongs to a different part of the relationship. Use the same named identification and limiter resources wherever their placeholders recur.

User-identification resource: Read the synthetic header to group requests by client.

{
  "spec": {
    "rules": [
      {
        "http_header_name": "X-CR-Client"
      }
    ]
  }
}

Rate-limiter resource: Reference that identification resource.

{
  "spec": {
    "user_identification": [
      {
        "name": "<USER_IDENTIFICATION_NAME>",
        "namespace": "<XC_NAMESPACE>"
      }
    ]
  }
}

Rate-limiter resource: Set five requests per minute, burst multiplier one, and a ten-second block action.

{
  "spec": {
    "limits": [
      {
        "total_number": 5,
        "unit": "MINUTE",
        "period_multiplier": 1,
        "burst_multiplier": 1,
        "token_bucket": {},
        "action_block": {
          "seconds": {
            "duration": 10
          }
        }
      }
    ]
  }
}

Load-balancer resource: Attach the limiter to the selected GET endpoint.

{
  "spec": {
    "api_rate_limit": {
      "no_ip_allowed_list": {},
      "api_endpoint_rules": [
        {
          "any_domain": {},
          "api_endpoint_path": "/demo/rate-limit",
          "api_endpoint_method": {
            "methods": [
              "GET"
            ]
          },
          "ref_rate_limiter": {
            "name": "<RATE_LIMITER_NAME>",
            "namespace": "<XC_NAMESPACE>"
          }
        }
      ]
    }
  }
}

Load-balancer resource: Supply the exact 429 custom body.

{
  "spec": {
    "more_option": {
      "custom_errors": {
        "429": "<ENCODED_RESPONSE_BODY>"
      }
    }
  }
}

The demonstration’s route also permits the documentation origin to read its responses, using the CORS relationship described in Cross-origin access.

Trigger and interpret the rejection

The focused widget sends seven fixed GET requests using a fresh synthetic client. It runs only when clicked, reserves fourteen requests including possible preflights, caps a page visit at 36 requests, and allows a run at most once per two minutes.

1. Select Trigger custom 429.
2. Compare the first five successful responses with the later 429 responses and custom body.

Expected result: The selected requests exceed the allowance and receive 429 with “Demo request limit reached”. A different synthetic client, POST request or unrelated path still reaches the origin. The measured API Rate Limiting event identifies the limiter as the block owner; the status alone does not.

The ten-second block duration is distinct from replenishing the request allowance. Recovery was measured after 65 seconds. The widget’s two-minute cooldown bounds repeated demonstrations; it does not measure recovery, and loading it sends no test requests.

Verified live example: Open the rate-limit endpoint. A single navigation does not demonstrate exceeding the allowance.