Rate Limiting

Чтобы защитить платформу от резких бросков нагрузки и фрода, Finance OS API применяет лимиты на каждый токен и каждый IP. Лимиты — мягкие: они не блокируют аккаунт, а только просят клиент сбавить темп и попробовать снова через Retry-After секунд.

Лимиты по умолчанию

Группы лимитов

Name	Type	Required	Description
`authenticated`	`60 req/min`	optional	Авторизованный пользователь (Bearer token). Считается на токен, не на IP.
`guest`	`10 req/min`	optional	Публичные endpoints без токена. Считается на IP.
`login`	`5 req/min`	optional	Endpoint `POST /mobile/login` — защита от brute-force. Считается на IP+email.
`webhook`	`без лимита`	optional	Входящие webhooks от платёжных и compliance-провайдеров — мы их доверяем по подписи, не по rate-limit.
`trading`	`300 req/min`	optional	`/api/trading/` и `/api/algo/` — выделенный пул для торговых ботов.

✦

Нужно больше?

Если ваш use-case требует более высокого RPS — напишите на admin@fin-os.io с указанием домена и ожидаемого паттерна нагрузки. Лимиты на партнёрских токенах настраиваются индивидуально.

Заголовки ответа

Каждый ответ (и успешный, и ошибочный) содержит три заголовка:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 47
X-RateLimit-Reset: 1716826421

Name	Type	Required	Description
`X-RateLimit-Limit`	`integer`	optional	Максимум запросов в минуту в текущей группе.
`X-RateLimit-Remaining`	`integer`	optional	Сколько осталось до окончания текущего окна (1 минута).
`X-RateLimit-Reset`	`integer (Unix timestamp)`	optional	Когда окно обнулится. Можно использовать для backoff.

Когда лимит превышен

HTTP 429 Too Many Requests, тело:

{
  "message": "Too Many Attempts.",
  "retry_after": 38
}

И заголовок Retry-After: 38 (секунды до возобновления). Клиент должен не повторять запрос немедленно — это эскалирует penalty.

Стратегия backoff

Рекомендация:

Поймали 429 → читаем Retry-After
Ждём Retry-After + jitter(0..5s) — jitter избегает «громыхающего стада»
Повторяем запрос
Если снова 429 — удваиваем delay (exponential backoff)
После 3 подряд 429 — фейлим операцию и алертим оператора

Параллельные запросы

Лимиты считаются по факту обработки — не по количеству открытых соединений. Поэтому несколько параллельных запросов от одного клиента съедают лимит так же, как последовательные. Если нужно много читать (например, синхронизация истории) — используйте пагинацию с per_page=100, а не 100 параллельных запросов с per_page=1.