Core API Rate Limiting

Each client is limited using a bursty rate limiting approach with two tiers:

• Primary limit: 1000 requests per minute (rolling window)
• Burst limit: 5000 requests per 5 minutes (rolling window)

How It Works

The rate limiter uses a two-tier system:

1. Primary limit: Your first 1000 requests per minute consume from the primary limit. This provides steady, consistent rate limiting.
2. Burst limit: Once the primary limit is exhausted, additional requests can consume from the burst limit (up to 5000 requests per 5 minutes). This allows for occasional traffic spikes while maintaining overall rate control.

Total capacity: You can make up to 1000 requests per minute consistently, with the ability to burst up to 5000 total requests within any 5-minute window.

Example Scenario

With limits of 1000/min (primary) and 5000/5min (burst):

• Requests 1-1000: Consume from primary limit ✅
• Requests 1001-5000: Consume from burst limit ✅ (if within 5-minute window)
• Request 5001: Both limits exhausted ❌

Rate Limit Errors

If you exceed the rate limit for your app on an organization, you will receive an HTTP 429 Too Many Requests response, with a body that looks something like this:

{
    "error": "rate_limit_exceeded",
    "message": "Rate limit exceeded",
    "limits": [
        {
            "type": "per_client_per_org",
            "limit": 1000,
            "retryAfter": 49
        }
    ]
}

• retryAfter is the number of seconds until you can make another successful request. This value represents the minimum wait time until the primary limit resets (typically ~60 seconds), which allows you to make at least one more request.
• limit indicates the primary limit that was configured.

Handling Rate Limits

Developers are responsible for ensuring they handle 429 responses and build out appropriate retry logic in the event of a rate-limited request. When implementing retry logic:

1. Respect the retryAfter value: Wait at least the number of seconds specified before retrying.
2. Use exponential backoff: Consider implementing exponential backoff for retries to avoid overwhelming the API.
3. Monitor your usage: Track your request patterns to optimize API usage and avoid hitting limits.

Developers are encouraged to optimize their use of our API to avoid these issues. If you are encountering a rate limiting issue that may highlight a limitation of our Core API, please contact our support team.

Core API is not an operational API

Core API is meant for maintenance tasks, syncing, and "behind the scenes" type work. Developers should avoid using it in high-volume, end-user facing flows, such as a web checkout. Our App API is our operational API for these sorts of tasks.