Configure API Rate Limits in GoodData.CN

GoodData.CN includes built-in rate limiting capabilities handled by the API Gateway microservice. This feature protects your API infrastructure from excessive usage and ensures fair resource allocation across clients. Administrators can define custom request limits based on various criteria such as client IP addresses, backend microservices, paths, HTTP methods, and organizations.

Rate limiting is disabled by default. This guide explains how to enable and configure it, define specific rules and filters, and monitor or adjust limits based on actual API traffic patterns. For general information about rate limiting behavior, response codes, and headers, see Rate Limiting documentation.

Enable and Configure Rate Limits

Rate limiting is configured through Helm chart values during deployment. No rate limits are configured by default, so it is the administrator’s responsibility to enable the feature and define the appropriate limits.

To activate rate limiting, set the following values in your Helm configuration:

apiGw:
  rateLimiter:
    enabled: true  # Must be set to true to activate rate limiting
    files:
      - name: your-limits.yaml
        content: |
          gateway:
            rateLimiter:
              limits:
                - name: "example-limit"
                  limit: 1000
                  windowSize: "60s"
                  loggingOnly: false          

Each rule defines how many requests are allowed in a given time window (limit, windowSize) and may include filters to determine which requests the rule applies to. Configuration is deployment-specific—there are no universal best practices, as optimal settings depend on your infrastructure and usage.

Configuration Parameters

Core Parameters

Request Filters

Optional filters define which requests the rule applies to. A request must match all specified filters:

Identification Keys

The keys parameter defines how requests are grouped and counted. Each unique combination of keys has its own counter.

• ip: per client IP address
• host: per backend microservice
• ["ip", "host"]: per IP + backend combination

Examples:

• No keys → 1000 requests/min total across all clients
• ["ip"] → 1000 requests/min per IP
• ["host"] → 1000 requests/min per backend service
• ["ip", "host"] → per IP+service combination

Define Rules and Filters

Below are example configurations illustrating common use cases:

Global API Limit

- name: "global-api-limit"
  limit: 10000
  windowSize: "1m"
  loggingOnly: false

Filtered by Path Pattern

- name: "api-endpoints-limit"
  limit: 5000
  windowSize: "1m"
  loggingOnly: false
  path: "/api/.*"

Filtered by Path and Method

- name: "search-get-limit"
  limit: 100
  windowSize: "1m"
  loggingOnly: false
  path: "/api/search"
  method: "GET"
  keys: ["ip"]

Organization-Specific Limit

- name: "org-specific-limit"
  limit: 5000
  windowSize: "1h"
  loggingOnly: false
  organizationId: "org-123"
  keys: ["ip"]

Combined Filters

- name: "org-api-post-limit"
  limit: 1000
  windowSize: "5m"
  loggingOnly: false
  organizationId: "org-456"
  path: "/api/v2/.*"
  method: "POST"

Backend Service Protection

- name: "backend-service-limit"
  limit: 500
  windowSize: "10s"
  loggingOnly: false
  keys: ["host"]

Per-Client and Backend Combination

- name: "client-backend-limit"
  limit: 100
  windowSize: "1m"
  loggingOnly: false
  keys: ["ip", "host"]

When multiple configuration files are used, later files override earlier ones if they share the same rule names.

Test and Monitor

Before enforcing rate limits, use logging-only mode to monitor behavior without rejecting requests:

- name: "monitoring-limit"
  limit: 1000
  windowSize: "1m"
  loggingOnly: true

In this mode:

• No 429 responses are sent
• No rate limit headers appear in responses
• Violations are logged for analysis

Determine Proper Limits

We recommend you cover the following steps when determining your API rate limits:

1. Start in logging-only mode to collect data.
2. Use metrics such as forward_call_response_status_count_total to observe request volume, patterns, and peak times.
3. Analyze API Gateway logs (action=serverHttpRequest) to identify request distribution and client behavior.
4. Set initial limits at 2–3× your observed peak traffic.
5. Tune downward gradually based on usage and performance.
6. Monitor continuously and adjust as necessary.

It’s safer to start with higher limits and tighten gradually rather than risk blocking legitimate traffic.

Manage Performance and Updates

The rate limiter uses a fixed window strategy, ensuring consistent enforcement across all API Gateway instances. When multiple rules apply to a request, the most restrictive limit is enforced. A request must match all filters (organizationId, path, method) for a rule to apply. If no filters are specified, the rule applies globally.

Example scenario:

• Rule A: 1000 req/min for path /api/.*
• Rule B: 100 req/min for /api/search (method GET)
• Rule C: 500 req/10s per backend service (keys: ["host"])

A GET request to /api/search matches Rules A and B; Rule B applies as it’s more restrictive, while Rule C enforces backend protection. Non-logging-only limits take precedence, and headers reflect the most restrictive active limit.

Rate limit counters only update for non-rejected requests. Configuration changes are applied via Helm updates and propagate automatically across all API Gateway pods without downtime.

When rate limiting is active, API responses include standard rate limit headers. For full details, see Rate Limiting documentation.

Monitor key indicators to assess impact:

• Violations: check logs for action=rateLimitExceeded
• Rejected Requests: monitor rate_limited_requests metric
• Client Impact: review 429 response rates by client or organization

Get Help

For assistance with configuring or troubleshooting rate limits, contact our support team and include:

• Deployment specifications
• Current configuration
• Observed traffic metrics and logs
• Backend service capacity details
• Description of issues or performance concerns