Skip to Content
API ReferenceRate Limits

Rate Limits

VoxBurst applies rate limiting to every authenticated API request. Limits are applied per API key (or per Cognito session) and vary by plan — higher plans receive higher limits.

Do not hard-code a specific limit. Read the current value from the X-RateLimit-Limit response header on every request instead — the effective limit can change without notice, and this repo’s security policy does not publish specific numeric thresholds in public documentation. Treat the limit as dynamic and design your client to back off based on the headers below, not on an assumed constant.

How It’s Applied

  • Rate limiting happens after authentication succeeds. A 401 response (missing or invalid credentials) does not include rate-limit headers, and does not count against your limit.
  • Unauthenticated public endpoints (like GET /v1/health) are not rate-limited by this mechanism and do not include these headers either.
  • Every successful, authenticated response includes the headers below, whether or not you are close to the limit.

Response Headers

HeaderDescription
X-RateLimit-LimitMaximum requests allowed in the current window
X-RateLimit-RemainingRequests remaining in the current window
X-RateLimit-ResetUnix timestamp when the current window resets
HTTP/1.1 200 OK
Content-Type: application/json
X-RateLimit-Limit: <requests allowed in the current window>
X-RateLimit-Remaining: <requests remaining in the current window>
X-RateLimit-Reset: <unix timestamp when the window resets>
 
{
  "id": "post_abc123",
  "content": "Hello from VoxBurst!",
  "status": "scheduled"
}

When You’re Rate Limited

When the limit is exceeded, the API returns 429 Too Many Requests with a Retry-After header indicating how many seconds to wait before retrying:

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Try again later."
  }
}
StatusCodeCause
429RATE_LIMITEDToo many requests in the current window
  • Track X-RateLimit-Remaining and slow down proactively as it approaches zero, rather than waiting to hit 429.
  • On 429, respect Retry-After exactly rather than retrying immediately or on a fixed interval.
  • Use exponential backoff with jitter for repeated 429s, in case of a sustained burst.
  • Use a separate API key for development and production so a runaway dev script cannot exhaust your production rate limit budget (this also limits the blast radius of a leaked key — see Authentication).

Endpoint-Specific Limits

A small number of endpoints apply their own, tighter rate limit independent of the general per-key limit described above (for example, the GDPR data export endpoint is limited to a low fixed number of requests per hour, and certain audit/history endpoints cap requests per minute). Where this applies, it is called out on that endpoint’s own reference page along with its specific 429 behavior.

Last updated on
PostsReports