Rate Limits

The Annie Insights API enforces rate limits to ensure fair usage and system stability.

Limits by Key Type

Key Type	Rate Limit	Burst	Daily Cap
Sandbox	10 req/min	5 concurrent	500/day
Production	Custom	Custom	Custom

Rate Limit Headers

Every API response includes rate limit information in the headers:

Header	Description
X-RateLimit-Limit	Maximum requests allowed in the current window
X-RateLimit-Remaining	Requests remaining in the current window
X-RateLimit-Reset	Unix timestamp when the window resets
Retry-After	Seconds to wait before retrying (only on 429)

Handling Rate Limits

When you exceed the rate limit, the API returns HTTP 429:

{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Retry after 60 seconds.",
  "statusCode": 429
}

Best Practices

1. Monitor headers — Check X-RateLimit-Remaining before sending requests
2. Queue requests — Implement a request queue with controlled throughput
3. Exponential backoff — On 429, wait 2^attempt seconds before retrying
4. Contact sales — For higher limits, contact api-support@hcds.ai