Rate Limits - Junis

Overview

The Junis External API implements rate limiting to ensure fair usage and maintain service quality for all users. Rate limits are applied per API key, and all keys of an organization also share one organization-wide total per minute and per hour. You can set each key’s limits yourself, up to 1,000 requests per minute and 100,000 per hour. Base URL: https://api.junis.ai

Each API key has its own per-minute and per-hour counters. On top of that, all keys of an organization share one total (300 requests per minute by default), so creating more keys does not raise the organization’s total.

Rate Limiting Architecture

The External API uses Redis-based fixed-window counters with up to four windows (per key per minute, per key per hour, per organization per minute, and per organization per hour when set) for distributed rate limiting across multiple server instances.

How It Works

Storage: Redis with distributed support across all API serversWindows: Four fixed windows aligned to the clock

Per key, per minute: resets at the start of every minute
Per key, per hour: resets at the start of every hour
Per organization, per minute: all keys of the organization combined, resets at the start of every minute
Per organization, per hour: all keys combined, resets at the start of every hour. Only applies when your organization has an hourly total set; only requests that passed every per-minute check count toward it

Algorithm: Fixed-window counters with atomic increments (one Redis round trip per request)

Rate Limit Enforcement

Check Before Request: Rate limits are checked before processing your requestHeaders Included: Every response includes current rate limit status429 on Exceed: Returns 429 Too Many Requests if limit exceededAutomatic Reset: Counters automatically reset at the end of each window

Default Rate Limits

When you create a new API key, the following default limits apply:

Limit	Organization key (Admin → API Keys)	Personal key (Settings → API Keys)
Requests per minute, per key	100	100
Requests per hour, per key	3,000	2,000
Requests per minute, whole organization	300 (all keys combined)	300 (all keys combined)
Requests per hour, whole organization	No separate limit (at most 60 × per minute)	No separate limit (at most 60 × per minute)

Changing the limits

Limit	Who can change it	Where	Range
Organization key	Organization owner or admin	Admin → API Keys: fill in Rate limits when you create a key, or press the gauge button on an existing key	1–1,000 per minute, 1–100,000 per hour
Personal key	The key’s owner	Settings → API Keys: same fields and gauge button	1–1,000 per minute, 1–100,000 per hour
Whole organization	Junis	Contact us with your expected traffic	up to 1,000 per minute, 100,000 per hour

The per-hour value must be at least the per-minute value. Leave a field blank to keep the default. Changes apply from the next request, with no redeploy.

The same per-key change is available from code through the admin API: PUT /api/admin/api-keys/{key_id} (organization keys) or PUT /api/user/api-keys/{key_id}/rate-limits (personal keys) with rate_limit_per_minute and/or rate_limit_per_hour. Raising a key above the organization total does not help: every request also counts toward the organization total.

Rate Limit Headers

Every API response includes headers that show your current rate limit status.

Response Headers

X-RateLimit-Limit-Minute: 100
X-RateLimit-Remaining-Minute: 55
X-RateLimit-Reset-Minute: 1767261600
X-RateLimit-Limit-Hour: 3000
X-RateLimit-Remaining-Hour: 2950
X-RateLimit-Reset-Hour: 1767261600
X-RateLimit-Limit-Org-Minute: 300
X-RateLimit-Remaining-Org-Minute: 240

Header	Description
`X-RateLimit-Limit-Minute`	Maximum requests allowed per minute for this key
`X-RateLimit-Remaining-Minute`	Requests remaining for this key in the current minute window
`X-RateLimit-Reset-Minute`	Unix timestamp when the minute window resets
`X-RateLimit-Limit-Hour`	Maximum requests allowed per hour for this key
`X-RateLimit-Remaining-Hour`	Requests remaining for this key in the current hour window
`X-RateLimit-Reset-Hour`	Unix timestamp when the hour window resets
`X-RateLimit-Limit-Org-Minute`	Maximum requests per minute for all keys of your organization combined
`X-RateLimit-Remaining-Org-Minute`	Requests remaining for the whole organization in the current minute window (resets with the minute window)
`X-RateLimit-Limit-Org-Hour`	Only when your organization has an hourly total: maximum requests per hour for all keys combined
`X-RateLimit-Remaining-Org-Hour`	Only when your organization has an hourly total: requests remaining in the current hour window

Responses also carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Window without a suffix. Those belong to a platform-level flood guard in front of the key limiter and are not your key’s quota — read the suffixed headers above.

Always monitor X-RateLimit-Remaining-* headers to avoid hitting rate limits. Consider pausing requests when remaining count is low.

429 Too Many Requests

When you exceed your rate limit, the API returns a 429 status code.

Response Format

HTTP Status:

HTTP/1.1 429 Too Many Requests
Retry-After: 45

Headers:

X-RateLimit-Limit-Minute: 100
X-RateLimit-Remaining-Minute: 0
X-RateLimit-Reset-Minute: 1767261600
X-RateLimit-Limit-Hour: 3000
X-RateLimit-Remaining-Hour: 2950
X-RateLimit-Reset-Hour: 1767261600
X-RateLimit-Limit-Org-Minute: 300
X-RateLimit-Remaining-Org-Minute: 180
Retry-After: 45

Body:

{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded: 100 requests per minute",
  "limit": 100,
  "window": "minute",
  "reset_at": 1767261600,
  "retry_after": 45
}

Field	Description
`error`	Error type: `rate_limit_exceeded`
`message`	Human-readable error message
`limit`	The rate limit that was exceeded
`window`	Which window was exceeded: `minute`, `hour` (this key), `org_minute` or `org_hour` (all keys of the organization)
`reset_at`	Unix timestamp when the window resets
`retry_after`	Seconds to wait before retrying

When the organization-wide total is exceeded, window is org_minute, limit is the organization total and message reads Organization rate limit exceeded: 300 requests per minute across all API keys. The organization per-hour total works the same way with window set to org_hour. The windows are checked in this order: key per minute, key per hour, organization per minute, organization per hour.

Handling Rate Limits

Best Practices

Monitor Headers: Always check X-RateLimit-Remaining-Minute, X-RateLimit-Remaining-Hour, X-RateLimit-Remaining-Org-Minute (and X-RateLimit-Remaining-Org-Hour if present) headers to track your usage
Implement Exponential Backoff: When you receive a 429 response, use the Retry-After header value to wait before retrying
Cache Responses: Implement caching (TTL: 5 minutes recommended) to reduce API calls for frequently accessed data
Batch Requests: Use paginated endpoints instead of individual requests (e.g., GET /api/external/sessions?limit=100)
Use Streaming: For real-time chat, use stream: true parameter instead of polling to avoid repeated API calls

Rate Limit Optimization

Identify Bottlenecks

Log Rate Limit Headers: Track X-RateLimit-Remaining-* headers in your application logs
Analyze Request Patterns: Identify high-frequency endpoints that may benefit from caching or batching
- Repeated session fetches → Add caching
- Individual message fetches → Use paginated list endpoints
- Polling for updates → Switch to streaming
Implement Caching: Use Redis or in-memory cache with 5-minute TTL for frequently accessed data
Monitor & Alert: Set up alerts when rate limit usage exceeds 90%

Testing Rate Limits

Local Testing

Test your rate limit handling before deploying to production:

# Test the per-key minute limit (default 100 per minute — send 105 requests in 1 minute)
for i in {1..105}; do
  curl -s -o /dev/null -w "%{http_code}\n" \
    https://api.junis.ai/api/external/v1/chat/completions \
    -H "X-API-Key: jns_live_YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"messages":[{"role":"user","content":"test"}]}'
  sleep 0.5
done

Increasing Rate Limits

Per-key limits are stored on the key itself, so they can be changed without redeploying anything:

An organization admin calls PUT /api/admin/api-keys/{key_id} (JWT authentication) with rate_limit_per_minute (1–1,000) and/or rate_limit_per_hour (1–100,000).
The new values apply from the next request made with that key.

Only organization admins can modify API key rate limits. Raising a key above the organization-wide total (300 requests per minute across all keys by default) does not add capacity on its own — the organization total still applies. Contact Junis to raise the organization total.

Set rate limits based on your actual usage patterns. Start conservative and increase as needed.

FAQs

Are rate limits per organization or per API key?

Answer: Both. Each key has its own per-minute and per-hour limits, and all keys of the organization share one per-minute total (300 by default).Example: If your organization has 2 API keys:

API Key 1: 100 requests/minute
API Key 2: 100 requests/minute
Organization total: 300 requests/minute — the keys together can never exceed it, so adding a third key does not add capacity beyond the total

What happens if I exceed rate limits?

Response: 429 Too Many Requests with Retry-After headerAction: Wait for the number of seconds specified in Retry-After or until the next window resetNo penalties: No account suspension or additional charges

Can I request a temporary rate limit increase?

Per key: Yes — an organization admin updates the key through the admin API (PUT /api/admin/api-keys/{key_id}), and the change applies from the next requestOrganization total: Contact Junis

Do streaming responses count differently?

Answer: Streaming responses count as 1 request, regardless of how long the stream lasts.Example:

Non-streaming: 1 request = 1 complete response
Streaming: 1 request = entire conversation stream

Streaming is more efficient for real-time chat.

How do I monitor my rate limit usage?

Method 1: Check response headers (X-RateLimit-Remaining-*)Method 2: Set up logging in your application (see Best Practices)Method 3: Monitor 429 error rates in your application metrics

Next Steps

Authentication

Learn about API keys and scopes

Error Codes

Handle 429 and other API errors

Chat Completions API

Start building with streaming

Sessions API

Manage chat sessions efficiently

​Overview

​Rate Limiting Architecture

​Default Rate Limits

​Changing the limits

​Rate Limit Headers

​Response Headers

​429 Too Many Requests

​Response Format

​Handling Rate Limits

​Best Practices

​Rate Limit Optimization

​Identify Bottlenecks

​Testing Rate Limits

​Local Testing

​Increasing Rate Limits

​FAQs

​Next Steps

Authentication

Error Codes

Chat Completions API

Sessions API

Overview

Rate Limiting Architecture

Default Rate Limits

Changing the limits

Rate Limit Headers

Response Headers

429 Too Many Requests

Response Format

Handling Rate Limits

Best Practices

Rate Limit Optimization

Identify Bottlenecks

Testing Rate Limits

Local Testing

Increasing Rate Limits

FAQs

Next Steps