Rate Limiting

Requests to the Karia API authenticated with an x-api-key header are rate limited per API key using a fixed 60-second window. The window starts on the first request for a key and resets 60 seconds later.

Endpoints that do not use x-api-key authentication are not covered by this policy.

Default Limit

Each key may make 120 requests per 60-second window (an average of 2 requests/second). Bursts are allowed as long as the window total stays at or below 120.

• 20 requests in one second, then idle for the rest of the window — allowed.
• 121 or more requests in the same 60-second window — rejected.

Requests rejected with 429 do not count toward the window.

Keys granted a higher limit will see their allowance reflected in X-RateLimit-Limit instead of 120.

Response Headers

Every API-key response includes the current window state:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 97
X-RateLimit-Reset: 42

When the Limit is Exceeded

Requests over the limit return HTTP 429 Too Many Requests with a Retry-After header. The value is the number of seconds to wait and matches X-RateLimit-Reset.

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 18
Retry-After: 18

{ "error": "Rate limit exceeded. Please retry after 18 seconds." }

Wait at least Retry-After seconds before retrying. Do not continue sending requests while X-RateLimit-Remaining is 0.

Best Practices

• Read Retry-After from the response rather than hard-coding a fixed delay.
• Add a small amount of jitter to retries so multiple clients don't retry in lockstep.
• Never retry in a tight loop — treat 429 as a signal to back off, not to try again immediately.
• Monitor X-RateLimit-Remaining and throttle proactively before you hit 0.
• Spread scheduled or batch jobs across the window instead of firing them all at once.

Requesting a Higher Limit

If you or your team need a higher rate limit, email support@karia.com.au with the subject line API key rate limit increase.

Include:

• The API key name (not the secret)
• Your organisation
• The limit you're requesting and why you need the extra throughput

Increases are applied per API key. We'll respond within 2 business days.

Next Steps

1. Confirm your key is set up with Getting an API Key.
2. Continue to Quick Start for a recommended onboarding path.
3. Use the OPENAPI reference for endpoint-level request and response details.