Issue Description
Developers may intermittently encounter rate-limiting errors when executing requests against the Agora Analytics REST API, specifically the call/lists endpoint. This phenomenon often persists even when individual scripts or local environments appear to operate within standard volume thresholds. The disruption is characterized by the sudden rejection of API calls, preventing the collection of real-time or historical session data.
Platform/SDK
Service: Agora Analytics REST API
Affected Endpoints:
/beta/analytics/call/listsand similar data inquiry interfaces
Error Characterization
The API returns a JSON response indicating a service package violation:
{
"code":300,
"message":"Service package limit check error, qps limit error",
"data":null
}
Root Cause
The primary cause of this error is the exceeding of the Queries Per Second, or QPS, quota enforced at the account or App ID level. Unlike client-side SDK limits, REST API quotas are cumulative across all originating sources.
In distributed server environments, this issue is frequently traced to duplicate or uncoordinated cron jobs. If multiple containers, cloud instances, or background workers utilize identical API credentials to poll the service simultaneously, the aggregate traffic will surpass the allocated capacity. This result occurs because the backend gateway does not distinguish between individual servers but evaluates the total request frequency of the entire account.
Step-by-Step Solution
-
Conduct an Infrastructure Audit
Perform a comprehensive audit of all server-side environments to identify redundant tasks. Verify whether identical scheduled scripts or containerized services are running in parallel across multiple availability zones or staging environments using the same production credentials.
-
Analyze Aggregate Traffic Volume
Calculate the total number of requests transmitted per second from all active instances. Ensure that the combined frequency remains below the limit defined in your Agora service plan. Developers must account for the peak concurrent load rather than the average execution time of a single script.
-
Implement Request Pacing and Throttling
Introduce a mandatory delay between paginated requests within your application logic. Avoid executing rapid, back-to-back page fetches. Implementing a client-side throttle ensures that the application maintains a consistent and predictable request cadence, even during large data exports.
-
Centralize Data Polling Tasks
Migrate from a distributed polling architecture to a centralized model. If possible, designate a single, dedicated server or a master service instance to handle all Analytics API interactions. This centralization eliminates the risk of accidental concurrency and simplifies rate-limit management.
-
Integrate Resiliency with Exponential Backoff
Modify the API client to handle HTTP 300 status code gracefully. Implement an exponential backoff algorithm for retry attempts. By increasing the wait time between successive retries, the system provides the API gateway with sufficient window to reset the QPS counter, ensuring eventually consistent data delivery.
-
Optimize Pagination Efficiency
Maxmize the
page_sizeparameter to the highest supported limit to reduce the total number of discrete API calls required for a full dataset. Configure the logic to terminate the sequence immediately upon receiving an empty result set, preventing unnecessary requests to the server.
Best Practice
Unified Rate Control: Implement a global rate-limiting middleware if your architecture requires multiple services to access the API.
Quota Monitoring: Regularly monitor the usage metrics in the Agora Console to align your request volume with your current service plan.
Environment Isolation: Use separate App IDs or projects for testing and production to prevent staging tasks from exhausting the production QPS quota.
Operational Documentation: Maintain clear documentation of all deployed cron jobs and their respective scheduling intervals to avoid unintended overlaps during scaling.