# 5. Rate Limiting

# Rate Limiting and Stability Guidelines

This section explains the platform’s **quota and rate limiting mechanisms**, **stability boundaries**, and recommended **integration and fault-tolerance strategies** to ensure the stable operation of both systems.

---

## 1. Purpose of Service Rate Limiting

Rate limiting is used to ensure:

- **Service stability**: Preventing sudden traffic spikes from causing interface congestion or overall unavailability
- **Fair usage**: Ensuring consistent service capacity for different customers based on quotas
- **Cost control**: Large-scale data computation and retrieval must be coordinated with the quota mechanism

---

## 2. Rate Limiting and Quota Policies

### 2.1 Rate Limiting/Quota Dimensions

The platform may impose restrictions based on the following dimensions (subject to actual activation or contractual agreements):

- **Maximum Calls per Minute**: Frequency control at the minute level
- **Daily Call Limit**: Control over the cumulative number of calls on a given day
- **QPS (Requests Per Second)**: API calls under the same API Key share a common QPS limit
- **Point Balance**: Points are consumed based on the API and query scope; calls cannot be made if the balance is insufficient

### 2.2 Return Codes Upon Triggering

When rate limiting or quota restrictions are triggered, the API will return a business error code (see the “Request and Response Specifications” section for details). Common codes include:

- **429**: API is rate-limited (API access exceeds the QPS threshold)
- **60004**: Reached the maximum number of calls per minute
- **60003**: Reached the maximum number of calls per day
- **60005**: Insufficient credit balance

### 2.3 API QPS List

| API Code | API Name | QPS Value |
|---:|---|---|
| 1001 | Application Basic Information | 20 times/second |
| 1002 | Application Extended Information | 20 times/second |
| 1020 | Application Information (Basic + Extended) | 10 times/second |
| 1003 | Application Visibility Trend | 5 times/second |
| 1004 | Apps by Same Developer | 10 times/sec |
| 1005 | Chart Ranking History | 5 times/sec |
| 1006 | Featured Recommendations | 5 times/sec |
| 1007 | Ratings and Reviews | 10 times/sec |
| 1008 | Version History | 5 times/sec |
| 1009 | Competitor Comparison Analysis | 5 times/sec |
| 1010 | Competitor Query | 10 times/sec |
| 1011 | Covered Keywords | 5 times/sec |
| 1012 | Expanded Keywords | 5 times/sec |
| 1013 | ASA Bid Keywords | 5 times/sec |
| 1014 | ASA Cycle Monitoring | 20 times/sec |
| 1015 | CPP Ad Records (App) | 10 times/sec |
| 1016 | App Tags | 10 times/sec |
| 1017 | Download Revenue Estimate | 20 times/sec |
| 1018 | Smart Recommendation Keywords | 10 times/sec |
| 1019 | Active User Analysis | 5 times/sec |
| 2001 | Real-time Chart Rankings | 5 times/sec |
| 2002 | Global/Regional Charts | 5 times/sec |
| 2003 | Keyword Search Index Chart | 1 time/sec |
| 2004 | Download Revenue Chart | 5 times/sec |
| 2005 | User Activity Chart | 5 times/sec |
| 2006 | Listing History Monitoring | 5 times/second |
| 2007 | Deleted Keyword History | 5 times/second |
| 2008 | Chart Drop History | 5 times/second |
| 3001 | Bidding App Charts | 5 times/second |
| 3002 | Popular Bidding Keywords (Country) | 5 times/sec |
| 3003 | Keyword Bidding Applications | 5 times/sec |
| 3004 | CPP Ad Records | 5 times/sec |
| 4001 | Keyword Application Search | 10 times/sec |
| 4002 | Keyword Expansion | 5 times/sec |

---

## 3. Stability Notes

### 3.1 Availability and Data Timeliness

The platform will make every effort to ensure API availability and response speed; however, **data delays** or **temporary unavailability** may occur under the following circumstances:

- **Data Source Synchronization Delay**: Delays in updates from third-party data sources
- **System Maintenance or Upgrades**: May result in temporary unavailability or performance fluctuations
- **Short-Term Traffic Surge**: The platform will trigger protective rate limiting

### 3.2 Explanation of “No Data Available”

For task-based or asynchronous result interfaces, if the task has not yet been completed or no results are currently available, the following responses may be returned:

- **60008: No Data Available** (Task data has not been fully processed or no data is currently available to return)

We recommend waiting and retrying according to the interface documentation to avoid high-frequency polling.

---

## 4. Integration and Usage Recommendations

### 4.1 Rate Limiting

- **Avoid High-Frequency Polling**: We recommend setting a reasonable refresh interval based on your business scenario (e.g., minutes or hours); polling at the second level is not recommended. For asynchronous task-based APIs, we suggest performing periodic queries by combining the `60008` (No Data Available) status with the task completion status.
- **Fetch on Demand**: Prioritize fetching only necessary fields and time ranges to reduce unnecessary requests.

### 4.2 Batch Retrieval Strategies

- **Batch Retrieval**: Split batches by `region`, time range, and application list
- **Concurrency Control**: Use a fixed-size concurrency pool (e.g., 5/10/20 concurrent requests) and ensure the overall rate does not exceed **20 requests per second** to avoid instantly exhausting the quota
- **Serialized/Limited Concurrency for Pagination**: For paginated results with `next-page`, it is recommended to retrieve them serially or with low concurrency

### 4.3 Retry Strategy (Recommended)

- **Exponential Backoff + Jitter**: For recoverable errors such as 429, 60004, and 510, use exponential backoff combined with random jitter. Reference: 200ms → 400ms → 800ms → 1600ms (with ±20% random jitter each time).
- **Maximum Retry Count**: 3–5 retries are recommended; avoid infinite retries.
- **Scenario-Specific Handling**:
  - `60003` (Daily Limit): It is recommended to suspend batch tasks for the day and resume the next day, or contact support to increase the quota.
  - `60005` (Insufficient Credits): It is recommended to top up credits first or adjust the query scope (narrow the time window/reduce metrics).
  - `60008` (No data available): Wait and retry as recommended by the API; avoid intensive polling.
- **Idempotency**: Query-type requests can generally be safely retried; if extended to write-type interfaces in the future, idempotency strategies will be documented separately.

### 4.4 Caching and Fallback

- **Caching Recommendations**: For data that changes infrequently (e.g., application basic information), caching is recommended (e.g., 6–24 hours).
- **Failover Strategy**: When encountering rate limiting or system exceptions, prioritize returning cached results or prompting the user to retry later.

---

## 5. Quota Increases and Support

To increase QPS, concurrency, or call limits, or to expand country coverage or historical data windows:

- Please contact Sales or Technical Support and provide: **customer ID, target API, estimated QPS/daily call volume, use case, and deployment timeline**
- We will evaluate your request based on your plan and actual load and provide a proposed adjustment plan

---