Rate Limits

Limits vary by plan and endpoint. Designed to prevent abuse while keeping the API fair for all accounts.

Rate Limit Tiers

Limits per plan for requests, messages, Dyvas, and knowledge documents.

Plan	Requests/min	Messages/day	Dyvas	Knowledge Docs
Free	30	50	3	5
Plus	120	500	25	50
Pro	300	2,000	100	200
Creator	600	10,000	Unlimited	500

Need higher limits? Upgrade your plan or contact us for custom enterprise quotas.

Rate Limit Headers

Every response includes rate limit headers. Use them to manage request flow proactively.

Header	Description
`X-RateLimit-Limit`	Maximum number of requests allowed in the current window.
`X-RateLimit-Remaining`	Number of requests remaining in the current window.
`X-RateLimit-Reset`	Unix timestamp (seconds) when the current window resets.

Example response headers

HTTP/1.1 200 OK
Content-Type: application/json
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 1741521600

429 Too Many Requests

Exceeding the rate limit returns a 429 status. The response body includes a retry_after field with the seconds to wait before retrying.

{
  "error": "rate_limit_exceeded",
  "message": "You have exceeded the rate limit of 120 requests per minute. Please wait before retrying.",
  "retry_after": 32
}

WarningDo not retry immediately. Respect the retry_after value. Repeated violations may trigger longer back-off periods or temporary suspension.

Best Practices

Build a resilient integration that stays within limits.

•Implement exponential backoff. On 429, wait for retry_after, then double the delay on each subsequent retry up to a maximum cap.
•Cache responses where possible. Dyva metadata, conversation lists, and configuration change infrequently. Cache locally to reduce API calls.
•Use webhooks instead of polling. Receive real-time push notifications instead of polling for new messages.
•Batch operations when available. Where available, combine multiple operations into a single API call.
•Monitor X-RateLimit-Remaining. Track remaining quota from response headers and throttle proactively.

Retry Logic Examples

Reusable pattern for rate limit handling with exponential backoff.

JSJavaScript

PyPython

async function fetchWithRetry(url, options = {}, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const res = await fetch(url, options);

    if (res.status !== 429) return res;

    // Parse retry delay from header or body
    const retryAfter = res.headers.get("Retry-After");
    const body = await res.json();
    const delay = (retryAfter ? parseInt(retryAfter) : body.retry_after) || 1;

    // Exponential backoff: retry_after * 2^attempt
    const backoff = delay * Math.pow(2, attempt) * 1000;
    console.warn(`Rate limited. Retrying in ${backoff / 1000}s...`);

    await new Promise((resolve) => setTimeout(resolve, backoff));
  }

  throw new Error("Max retries exceeded");
}

// Usage
const res = await fetchWithRetry("https://api.dyva.ai/v1/dyvas", {
  headers: { Authorization: `Bearer ${API_KEY}` },
});
const data = await res.json();

Endpoint-Specific Limits

Resource-intensive endpoints have lower limits than the per-plan defaults. These apply regardless of plan unless noted.

Endpoint	Free	Pro+
Voice TTS	100/min	500/min
File uploads	10/min	10/min
Search	60/min	60/min

Endpoint-specific limits are tracked independently from the global per-minute limit. A request can fail with 429 even if you have remaining global quota.

Embedding

Error Handling