Skip to content

Rate limits

Requests are throttled per client IP address, across all endpoints and all API keys used from that address.

Limit Value
Sustained rate 1 request per second
Burst 20 requests
Scope Client IP
Exempt GET /v1/health, CORS preflight requests

The allowance is a token bucket: it refills at 1 per second up to a ceiling of 20, so a client that has been idle can issue 20 requests at once and then settles to 1 per second.

Over the allowance, the API returns 429 with application/problem+json:

{
"type": "https://api.cotes.ai/problems/rate-limited",
"title": "Too Many Requests",
"status": 429,
"detail": "Rate limit exceeded. Retry shortly."
}

with these headers:

Header Example Meaning
Retry-After 1 Seconds to wait before retrying
X-RateLimit-Limit 20 Burst ceiling
X-RateLimit-Remaining 0 Requests left in the current allowance

These three headers are sent only on 429 responses — successful responses carry no rate-limit headers, so you cannot track remaining allowance from a 200. They are named in Access-Control-Expose-Headers, so browser clients can read them.

Wait for Retry-After seconds, then retry with exponential backoff and jitter. Treat 429 as retryable; do not count it as a signal that your key is invalid.

Terminal window
curl -sS --retry 5 --retry-delay 1 \
-H "Authorization: Bearer $COTES_API_KEY" \
"https://api.cotes.ai/v1/contests/active?series=KXBTC15M"

A live contest gains a new reading every few seconds, and the active contest is cached for one second, so polling /v1/contests/active more than once a second returns the same payload and spends allowance. Polling one series every few seconds fits comfortably. Polling all four that often uses most of the sustained rate, so stream instead.

For continuous updates, prefer streaming. Opening a stream costs one request against the allowance; the events that follow on that connection do not.

The MCP server draws on the same per-IP allowance. Each tool call or resource read spends two requests: one for the MCP request itself and one for the API call it makes. Listing tools and other protocol requests spend one. An idle client can make about 10 tool calls at once and then one every two seconds.

An address we have blocked gets 403 with the problem type forbidden on every request, whatever its allowance. Retrying does not help; ask in Discord if you think it is a mistake.