Rate limits

Each API key has two call budgets, and every call uses both:

Each budget is a bucket that starts full and refills at a steady pace. A key can spend a whole bucket at once, then keep calling at the refill pace. No window resets at a fixed time: the remaining calls climb back between calls.

The limits are the same for every key. Calls refused with 403 count against the budget too.

HeadersCopy Anchor Link

Every answer to a call with a valid key carries the state of both budgets, errors included:

A 401 and a 404 carry none of them: the API answers them before it looks at the budget of the key.

curl -i https://api.redokun.com/v1/me \
  -H "Authorization: Bearer rdk_..."

HTTP/2 200
content-type: application/json
x-ratelimit-limit-minute: 60
x-ratelimit-remaining-minute: 59
x-ratelimit-limit-hour: 1000
x-ratelimit-remaining-hour: 999

When a budget runs outCopy Anchor Link

A call made when either bucket is empty gets 429 with the code RATE_LIMITED. The Retry-After header tells how many seconds to wait. When both buckets are empty, it carries the longer of the two waits, so a call made after it does not get 429 again.

HTTP/2 429
content-type: application/json
retry-after: 12

{
  "status": "error",
  "error": "Too many requests. Slow down and retry after the time in the Retry-After header.",
  "code": "RATE_LIMITED"
}

Staying within the limitsCopy Anchor Link

• Read X-RateLimit-Remaining-Minute and X-RateLimit-Remaining-Hour, and slow down before they reach zero.
• On 429, wait the seconds in Retry-After before the next call. Do not retry at once: the call fails again.
• Spread long jobs over time instead of sending every call in one burst.