Rate limits

Shisa services apply rate limits and quota to keep the platform fast and fair for everyone. This guide explains what happens when you hit a limit and how to handle it gracefully.

Limits and quota

Requests can be subject to two layers of throttling:

• Global per-key limits cap requests made with one API key across services.
• Optional per-service limits independently cap requests to a particular routed service.
• Quota is your available balance — new accounts start with $10 in free credits, and premium plans add paid balance and higher limits.

The exact limits that apply to your account depend on your plan. Check your current limits and usage in the Shisa platform; for higher limits, upgrade your plan or contact sales from the platform.

note

The global bucket is keyed to the API key, not the whole account. A burst of LLM, ASR, TTS, and Translation requests made with the same key draws on that shared key-level limit. A configured service-specific limit is checked separately, so a request must pass both layers.

Realtime WebSocket services can also enforce a maximum number of active sessions per key and service.

When you exceed a limit

When you exceed a rate limit, the API responds with HTTP status 429 (rate limit exceeded). The right way to handle a 429 is to wait and retry rather than immediately re-sending the request, which would only add to the load.

Use exponential backoff: wait a short delay, then double it on each subsequent retry, up to a maximum number of attempts. Adding a little random jitter avoids many clients retrying in lockstep.

Python

import time
import random
import requests

def post_with_backoff(url, headers, json, max_retries=5):
    delay = 1.0  # seconds
    for attempt in range(max_retries):
        response = requests.post(url, headers=headers, json=json)
        if response.status_code != 429:
            return response
        # Rate limited — back off before retrying
        sleep_for = delay + random.uniform(0, 0.5)
        time.sleep(sleep_for)
        delay *= 2
    raise RuntimeError("Rate limit not cleared after retries")

JavaScript

async function postWithBackoff(url, options, maxRetries = 5) {
  let delay = 1000; // milliseconds
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, { ...options, method: 'POST' });
    if (response.status !== 429) {
      return response;
    }
    // Rate limited — back off before retrying
    const jitter = Math.random() * 500;
    await new Promise((resolve) => setTimeout(resolve, delay + jitter));
    delay *= 2;
  }
  throw new Error('Rate limit not cleared after retries');
}

tip

Build backoff into your client once and reuse it for every Shisa call. If you use the OpenAI SDKs for Shisa LLM, they already retry 429 responses with backoff automatically.

Reducing how often you hit limits

• Batch where you can instead of sending many tiny requests in a tight loop.
• Cache responses that do not change between requests.
• Stagger background jobs so they do not all fire at the same instant.
• Monitor usage in the platform and request higher limits before a launch rather than during one.

Next steps

• Errors — the full list of status codes and JSON error shapes.
• Authentication — keys, credits, and the shared authorization header.