rate-limits

HMS Sovereign applies rate limits to ensure fair usage and maintain service quality for all users.

Current Limits

Limit Type	Rate	Scope
API Requests	100 requests/minute	Per API key
Call Control	10 commands/minute	Per active call

Rate Limit Headers

Every API response includes headers to help you track your usage:

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed
`X-RateLimit-Remaining`	Requests remaining in current window
`X-RateLimit-Reset`	Unix timestamp when the limit resets

Exceeding the Limit

When you exceed the rate limit, the API returns:

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1702479600
Retry-After: 45

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Please retry after 45 seconds."
  }
}

Best Practices

1. Monitor Rate Limit Headers

Check headers before making requests:

2. Implement Exponential Backoff

When you receive a 429 response:

3. Cache Responses

Cache data that doesn't change frequently:

4. Batch Operations

Instead of multiple individual requests, use batch-friendly patterns:

5. Use Webhooks for Real-Time Data

Instead of polling for call status, use webhooks:

{
  "webhook_url": "https://your-domain.com/webhook",
  "webhook_events": ["status-update", "end-of-call-report"]
}

Call Control Limits

Call control commands have a separate limit of 10 commands per minute per active call. This prevents abuse while allowing normal interaction patterns.

Examples that count toward the limit:

inject-context

say

end-call

transfer

Higher Limits

If you need higher rate limits for your use case, contact support@hmsovereign.com with:

Your organization ID

Expected request volume

Use case description

Authentication

Error Codes

Call Control API

Current Limits#

Rate Limit Headers#

Exceeding the Limit#

Best Practices#

1. Monitor Rate Limit Headers#

2. Implement Exponential Backoff#

3. Cache Responses#

4. Batch Operations#

5. Use Webhooks for Real-Time Data#

Call Control Limits#

Higher Limits#

Related#