Основные понятия

Лимиты запросов

Каждый ключ может отправлять 120 запросов в минуту, и каждый ответ сообщает, сколько ещё осталось.

Лимиты

Лимит	К чему применяется
120 запросов в минуту	Каждый API-ключ, на всех эндпоинтах. Окно фиксированное и начинается ровно в начале минуты.
10 экспортов в час	Каждый аккаунт, в запросе Создание экспорта. При превышении ответ 429 `export_rate_limit_exceeded`.
10 DM в минуту	Каждый аккаунт X, в запросе Отправка сообщения. При превышении ответ 429 `dm_rate_limited`.
300 DM в сутки	Каждый аккаунт X, за сутки по UTC, или меньше, если X задаёт более низкую квоту. При превышении ответ 429 `dm_daily_limit`.
5 попыток ввода кода в час	Каждый аккаунт, в запросе Установка кода X Chat. При превышении ответ 429 `passcode_rate_limited`.
6 сообщений Julien AI в минуту	Каждый аккаунт X, в запросе Отправка сообщения и в MCP-инструменте `ask_julien_ai`. При превышении ответ 429 `assistant_rate_limited`.
100 сообщений Julien AI в сутки	Каждый аккаунт X, за сутки по UTC. При превышении ответ 429 `assistant_daily_limit`.
Одно сообщение Julien AI за раз	Каждый чат, и не больше 3 чатов одновременно на каждый аккаунт X. При превышении ответ 409 `assistant_busy`.

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

Каждый ответ сообщает состояние окна ключа.

Заголовок	Значение
`RateLimit-Limit`	Сколько запросов разрешено в одном окне, `120`.
`RateLimit-Remaining`	Сколько запросов осталось в текущем окне.
`RateLimit-Reset`	Через сколько секунд начнётся новое окно.
`Retry-After`	Только при 429, через сколько секунд можно повторить запрос.

Заголовки

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
RateLimit-Limit: 120
RateLimit-Remaining: 0
RateLimit-Reset: 17
Retry-After: 17
Request-Id: req_3Vb8YzC1dF6hJ0sW

Ответ429

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Too many requests. This key can make 120 requests a minute.",
    "param": null,
    "request_id": "req_3Vb8YzC1dF6hJ0sW",
    "doc_url": "https://gemlead.ai/docs/errors#rate_limit_exceeded"
  }
}

Обработка 429

Подождите Retry-After секунд, затем отправьте тот же запрос снова.

Распределяйте большие задачи во времени, а не отправляйте их пачками.
Следите за RateLimit-Remaining, чтобы снизить темп раньше, чем остаток дойдёт до нуля.
Чтобы получить много лидов сразу, один экспорт лучше сотен страниц.
Вебхуки сами присылают вам события, и вам не нужно тратить запросы на опрос новых лидов.

# curl waits for Retry-After, then tries again
curl --retry 5 https://gemlead.ai/api/v1/leads \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"