> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gameboost.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Rate Limiting

> Understand API rate limits and learn how to implement exponential backoff strategies

## Overview

The GameBoost API implements rate limiting to ensure fair usage and maintain service stability for all partners. Rate limits are applied per API key and tracked separately for read and write operations.

<Info>
  Rate limit information is included in every API response via headers, allowing you to implement proactive rate limit handling.
</Info>

## Rate Limit Tiers

Rate limits vary based on your operation type and partner tier:

### Standard Rate Limits

All partners have access to the following rate limits:

| Operation Type                      | Limit                     | Description                                                 |
| ----------------------------------- | ------------------------- | ----------------------------------------------------------- |
| **Read Operations** (GET)           | 1000 requests per minute  | All GET requests that retrieve data                         |
| **Write Operations** (Global)       | 500 requests per minute   | All POST, PUT, PATCH, DELETE requests combined              |
| **Write Operations** (Per Resource) | 5 per minute, 10 per hour | Writes to the same resource (e.g., updating the same order) |
| **Chat Operations** (Global)        | 5 per minute              | All message retrieval or submition requests                 |

<Note>
  The per-resource limit prevents excessive updates to individual resources.
</Note>

<Tip>
  Need higher limits for your use case? Contact our team on [Discord](https://discord.com/channels/499268368545611787/1234627294228779018) to discuss your requirements.
</Tip>

## Rate Limit Headers

Every API response includes headers that provide real-time information about your current rate limit status:

| Header                  | Description                                              | Example Value |
| ----------------------- | -------------------------------------------------------- | ------------- |
| `X-RateLimit-Limit`     | Maximum requests allowed per window                      | `1000`        |
| `X-RateLimit-Remaining` | Requests remaining in current window                     | `987`         |
| `X-Ratelimit-Reset`     | Unix timestamp when the limit resets                     | `1728649200`  |
| `Retry-After`           | Seconds to wait before retrying (only when rate limited) | `42`          |

### Example Response Headers

```http theme={null}
HTTP/1.1 200 OK
Content-Type: application/json
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 987
X-Ratelimit-Reset: 1728649200
X-GameBoost-Request-Id: req_abc123
```

<Tip>
  Monitor the `X-RateLimit-Remaining` header to implement proactive throttling before hitting the rate limit.
</Tip>

## Handling Rate Limits

### Rate Limit Response

When you exceed the rate limit, the API returns a `429 Too Many Requests` status code:

<CodeGroup>
  ```json 429 Too Many Requests theme={null}
  {
    "message": "Too many requests",
    "request_id": "0e8400-e29b..."
  }
  ```
</CodeGroup>

The response headers also provide rate limit information:

```http theme={null}
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-Ratelimit-Reset: 1728649200
Retry-After: 42
```

<Warning>
  Never ignore `429` responses. Implement proper retry logic with exponential backoff to avoid being temporarily blocked.
</Warning>

## Best Practices

<AccordionGroup>
  <Accordion title="Monitor rate limit headers">
    Always check the `X-RateLimit-Remaining` and `X-Ratelimit-Reset` headers in your responses. Use this information to implement intelligent throttling.

    ```javascript theme={null}
    function checkRateLimitHeaders(response) {
      const remaining = parseInt(response.headers.get('X-RateLimit-Remaining'));
      const reset = parseInt(response.headers.get('X-Ratelimit-Reset'));

      console.log(`Rate limit: ${remaining} requests remaining`);
      console.log(`Resets at: ${new Date(reset * 1000).toISOString()}`);

      // Warn if getting close to limit
      if (remaining < 10) {
        console.warn('Approaching rate limit!');
      }
    }
    ```
  </Accordion>

  <Accordion title="Implement exponential backoff">
    Always use exponential backoff when retrying rate-limited requests. This prevents overwhelming the API and helps distribute load.

    * Start with a 1-second delay
    * Double the delay with each retry
    * Cap the maximum delay at 60 seconds
    * Respect the `Retry-After` header when provided
  </Accordion>

  <Accordion title="Cache responses when appropriate">
    Cache API responses on your end to reduce the number of requests you need to make.

    ```javascript theme={null}
    class CachedAPIClient {
      constructor(apiKey) {
        this.cache = new Map();
        this.cacheDuration = 60000; // 1 minute
      }

      async get(endpoint) {
        const cached = this.cache.get(endpoint);

        if (cached && Date.now() - cached.timestamp < this.cacheDuration) {
          return cached.data;
        }

        const data = await this.fetchFromAPI(endpoint);
        this.cache.set(endpoint, { data, timestamp: Date.now() });

        return data;
      }
    }
    ```
  </Accordion>

  <Accordion title="Distribute load across time">
    If you need to process large batches of data, spread the requests over time rather than making them all at once.

    ```javascript theme={null}
    async function processLargeDataset(items, delayMs = 1000) {
      const results = [];

      for (const item of items) {
        results.push(await processItem(item));

        // Wait between requests to avoid rate limits
        await sleep(delayMs);
      }

      return results;
    }
    ```
  </Accordion>

  <Accordion title="Use webhooks instead of polling">
    Instead of repeatedly polling for updates, configure webhooks to receive real-time notifications. This dramatically reduces your API usage.

    See our [Webhooks Guide](/api/get-started/configure-webhooks) for setup instructions.
  </Accordion>
</AccordionGroup>

## Monitoring Rate Limit Usage

Track your rate limit usage to optimize your integration:

```javascript theme={null}
class RateLimitMonitor {
  constructor() {
    this.stats = {
      requests: 0,
      rateLimited: 0,
      retries: 0
    };
  }

  recordRequest(response) {
    this.stats.requests++;

    if (response.status === 429) {
      this.stats.rateLimited++;
    }

    // Log rate limit info
    console.log({
      timestamp: new Date().toISOString(),
      remaining: response.headers.get('X-RateLimit-Remaining'),
      reset: new Date(response.headers.get('X-Ratelimit-Reset') * 1000).toISOString()
    });
  }

  recordRetry() {
    this.stats.retries++;
  }

  getStats() {
    return {
      ...this.stats,
      retryRate: (this.stats.retries / this.stats.requests * 100).toFixed(2) + '%',
      rateLimitRate: (this.stats.rateLimited / this.stats.requests * 100).toFixed(2) + '%'
    };
  }
}
```

## Troubleshooting

### Getting rate limited frequently?

<AccordionGroup>
  <Accordion title="Check your request patterns">
    Review your API usage to identify patterns:

    * Are you making requests in tight loops?
    * Are you caching responses appropriately?
  </Accordion>

  <Accordion title="Implement request throttling">
    Add delays between requests or use a request queue to stay within limits.
  </Accordion>

  <Accordion title="Use webhooks instead of polling">
    Polling for updates can quickly consume your rate limit. Use webhooks for real-time notifications instead.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card icon="webhook" href="/api/get-started/configure-webhooks" title="Webhooks">
    Reduce API calls by using webhooks for real-time updates
  </Card>

  <Card icon="book" href="/api/reference/account-offers/list-account-offers" title="API Reference">
    Explore endpoints and their specific rate limits
  </Card>

  <Card icon="message" href="/api/get-started/api-responses" title="API Responses">
    Learn more about error handling
  </Card>

  <Card icon="key" href="/api/get-started/authentication" title="Authentication">
    Review authentication setup
  </Card>
</CardGroup>