Ошибка API rate limit exceeded: что значит и как её обойти

Ты сидишь и наблюдаешь, как ИИ пишет код в терминале, а через минуту вместо ответа видишь красную строку: rate limit exceeded или похожий текст про quota exceeded. Заявка не выполнена, работа встала. Первая мысль обычно «я что-то сломал». На самом деле нет: ты просто упёрся в защитный механизм, с которым сталкивается любой, кто вызывает внешний API, — от новичка на курсе до крупной компании. Разберём, что это за ограничение, почему оно срабатывает именно у тебя и что делать дальше, чтобы работа продолжилась.

Что такое rate limiting простыми словами

Rate limiting — это ограничение на количество запросов, которые сервис принимает от одного пользователя или приложения за определённый промежуток времени: минуту, час или сутки. Если лимит исчерпан, следующий запрос сервис не выполняет, а отклоняет с сообщением об ошибке.

Зачем это нужно самому сервису. Любой API — будь то Claude API, OpenAI API, Gemini API или GitHub API — работает на реальном оборудовании с конечной пропускной способностью. Если снять ограничения совсем, несколько крупных клиентов или один сорвавшийся с цепи скрипт могут забрать себе всю мощность серверов, и тысячи других пользователей останутся без ответа. Лимиты — это способ честно поделить общий ресурс между всеми и заодно защититься от перегрузки, случайной или намеренной.

Бытовая аналогия: представь кассу в супермаркете, где кассир физически может пробить не больше определённого числа товаров в минуту. Если один покупатель попытается провезти через кассу тысячу тележек подряд, очередь встанет для всех остальных. Лимит — это правило «не больше N товаров за один заход», которое держит очередь живой.

Ограничения бывают на разных уровнях, и часто действуют сразу несколько одновременно:

• По количеству запросов — сколько обращений к API можно сделать за минуту или за час.
• По объёму данных — сколько токенов текста (у языковых моделей) или байт можно передать и получить за период.
• По деньгам — суточный или месячный бюджет на аккаунте, после которого запросы блокируются независимо от технических лимитов.
• По параллельности — сколько запросов может выполняться одновременно, даже если общий лимит в минуту ещё не исчерпан.

У бесплатных и пробных тарифов лимиты обычно значительно ниже, чем у платных. Это нормальная практика: сервис даёт попробовать продукт бесплатно, но не готов бесконечно раздавать вычислительные мощности без оплаты.

Короткое и длинное окно лимита одновременно

У многих API работает не одно ограничение, а сразу несколько окон времени параллельно: например, лимит на минуту и отдельный лимит на сутки. Уложиться в минутный лимит не гарантирует, что не упрёшься в суточный, и наоборот. Если за час ты сделал немного запросов, но все их отправил тремя короткими всплесками подряд, минутное ограничение сработает раньше, чем ты успеешь заметить, что общий дневной объём ещё далёк от предела.

Это объясняет ситуацию, которая сбивает с толку многих новичков: вчера всё работало без единой ошибки, а сегодня ровно то же самое действие внезапно упирается в лимит. Дело не в том, что сервис стал строже, а в том, что счётчик короткого окна уже успел заполниться из-за нескольких запросов подряд буквально за последние секунды.

Как выглядит ошибка rate limit exceeded на практике

У большинства API ограничение по частоте запросов сигнализируется одним и тем же способом — HTTP-кодом ответа 429 Too Many Requests. Это стандартный код из спецификации HTTP, который означает: «сервер понял запрос, но отказывается его выполнять, потому что ты делаешь их слишком часто».

Рядом с кодом 429 сервис обычно присылает текстовое пояснение. Формулировки отличаются от провайдера к провайдеру, но по смыслу сводятся к одному и тому же:

• rate limit exceeded — превышен лимит частоты запросов;
• quota exceeded — исчерпана выделенная квота (обычно про объём или бюджет, а не про частоту);
• too many requests — прямой перевод кода 429 в текст;
• resource has been exhausted — вариант формулировки у некоторых моделей.

Выглядит это обычно так — сервис возвращает код ответа и короткое пояснение вроде:

HTTP/1.1 429 Too Many Requests
Retry-After: 20

{"error": {"type": "rate_limit_error", "message": "Number of request tokens has exceeded your rate limit"}}

Конкретные названия полей и формулировка текста ошибки отличаются от сервиса к сервису — это лишь иллюстрация общего вида ответа, а не точная цитата из документации конкретного провайдера.

Иногда ошибка приходит не напрямую от API, а через посредника — например, Claude Code в терминале покажет собственное сообщение о том, что достигнут лимит, и предложит подождать. GitHub Actions в логе сборки покажет, что шаг workflow упал с ошибкой сети или ответом 429 от того сервиса, к которому обращался твой скрипт.

Точные цифры лимитов — сколько именно запросов в минуту разрешено на бесплатном тарифе Claude API, OpenAI API или Gemini API — здесь сознательно не называю. Провайдеры меняют эти значения без предупреждения, разные тарифы дают разные лимиты, а для новых аккаунтов часто действуют дополнительные ограничения на первые дни. Актуальные цифры смотри в официальной документации: у каждого сервиса есть отдельная страница про rate limits, обычно в разделе для разработчиков — например, у Anthropic это docs.anthropic.com/en/api/rate-limits, а у GitHub — раздел про лимиты REST API в официальной документации GitHub. Забивать себе память чужими цифрами бессмысленно — они устареют быстрее, чем ты успеешь ими воспользоваться.

Похожие, но другие ошибки

Не всё, что выглядит как проблема с лимитом, ей на самом деле является. Рядом с 429 встречаются соседние ошибки, которые новичок легко перепутает:

Если сомневаешься, какая именно ошибка перед тобой, — открой полный текст ответа сервиса, а не только код. Почти всегда там прямо написано, в чём дело: не хватило прав, кончились деньги или именно превышен лимит запросов.

Как лимиты устроены у разных сервисов курса

Общий принцип у Claude API, OpenAI API, Gemini API и GitHub API одинаковый — ограничение по частоте запросов. Но считают они по-разному, и это влияет на то, откуда именно пришла ошибка.

Claude API

У Claude API ограничения обычно считаются сразу по нескольким параметрам: количество запросов в минуту и количество токенов (единиц текста, на которые модель делит запрос и ответ) в минуту. Длинный запрос с большим файлом кода на входе может исчерпать лимит по токенам быстрее, чем лимит по числу запросов, даже если самих запросов было немного. Claude Code, который ты используешь на курсе, обращается к этому же API под капотом, поэтому те же принципы применимы к нему напрямую.

OpenAI API

OpenAI API устроен похоже: лимиты считаются по запросам в минуту и по токенам в минуту, а конкретные значения зависят от тарифа и от того, как долго аккаунт существует и пополнялся. Учти, что у OpenAI действует отдельный набор лимитов на каждую модель — упереться в ограничение по одной модели не значит, что лимит исчерпан у всех остальных.

Gemini API

У Gemini API помимо лимита по запросам в минуту есть и суточный лимит на количество запросов — это особенно заметно на бесплатном тарифе, где дневная квота может закончиться раньше, чем минутная. Если работаешь с Gemini API в рамках курсового проекта, стоит проверять именно официальную страницу с лимитами сервиса, потому что бесплатные условия там меняются заметно чаще, чем у платных провайдеров.

GitHub API

GitHub API считает лимит иначе — по количеству запросов в час, а не в минуту, и делает существенную разницу между обращениями с аутентификацией (по токену) и без неё: у анонимных запросов лимит на порядок ниже. Если workflow в GitHub Actions обращается к GitHub API без явно переданного токена доступа, лимит закончится быстро просто потому, что запросы идут как анонимные. Проверить остаток лимита можно прямо из документации GitHub API — там описан отдельный эндпоинт, который возвращает текущее состояние лимита для твоего токена.

Почему это случается у новичка на курсе

На первый взгляд кажется, что упереться в лимит API — удел крупных проектов с миллионами пользователей. На практике новички натыкаются на эту ошибку даже чаще, чем опытные разработчики, просто по другим причинам.

Слишком частые вызовы ИИ в цикле

Когда Claude Code пишет и правит код за тебя, каждое обращение — редактирование файла, запуск команды, чтение результата — часто означает отдельный вызов модели. Если задача сформулирована широко («перепиши весь проект» вместо «поправь одну функцию») или в процессе работы происходит ошибка и агент начинает по кругу пробовать разные варианты, количество запросов за короткое время резко растёт. Особенно это заметно, если несколько ИИ-агентов работают параллельно над одним и тем же аккаунтом — они делят один и тот же лимит, а не получают по отдельному на каждого.

GitHub Actions на каждый коммит

Многие сборки настраивают так, чтобы workflow в GitHub Actions запускался автоматически при каждом пуше в репозиторий. Если внутри такого workflow есть шаг, который дёргает внешний API — например, отправляет запрос к ИИ-сервису для генерации текста, проверяет данные через сторонний сервис или обращается к самому GitHub API для получения информации о репозитории, — то серия коммитов подряд (обычное дело, когда правишь код мелкими шагами) превращается в серию запросов подряд. У GitHub API, кстати, есть собственные лимиты на количество обращений в час, и они отдельные от лимитов внешних ИИ-сервисов, к которым ты можешь обращаться из того же workflow.

Низкий лимит бесплатного тарифа

Бесплатные и пробные тарифы у ИИ-сервисов рассчитаны на знакомство с продуктом, а не на интенсивную ежедневную работу. Пока ты проходишь курс и экспериментируешь с разными формулировками задач, легко не заметить, как быстро расходуется дневная или месячная квота бесплатного плана. Разные сервисы считают лимиты по-разному: где-то ограничение по числу запросов в минуту, где-то по количеству обработанных токенов текста, где-то одновременно и так, и так.

Совпадение нескольких факторов

Хуже всего, когда причины накладываются друг на друга: ты запускаешь ИИ-агента на бесплатном тарифе, у агента настроен автоматический перезапуск при ошибке, а рядом ещё крутится GitHub Actions, который на каждый коммит дёргает тот же самый сервис. Тогда лимит закончится быстро и незаметно, а разбираться, что именно его исчерпало, придётся по логам.

Как одна широкая задача превращается в десятки запросов

Показательный пример из практики курса. Ты просишь агента «сделай так, чтобы игра сохраняла рекорд и красиво его показывала». Задача звучит как одна фраза, но для ИИ она разворачивается в цепочку действий: прочитать текущий файл кода, написать функцию сохранения, проверить, что она не ломает остальное, запустить игру, увидеть ошибку в консоли, прочитать её, исправить, запустить снова, добавить стили для отображения рекорда, снова проверить. Каждое из этих действий по отдельности может означать обращение к модели. Если на середине пути что-то пошло не так и агент несколько раз подряд пробует разные подходы к одной и той же ошибке, счётчик запросов растёт быстрее, чем кажется со стороны.

Это не повод переписывать задачи короче искусственно — короткая, но расплывчатая формулировка («поправь игру») спровоцирует ещё больше уточняющих действий. Смысл в другом: чем точнее сформулирована задача с самого начала, тем меньше агенту приходится гадать и пробовать заново, а значит, меньше и лишних запросов к API.

Что делать, когда увидел rate limit exceeded

Реакция «просто нажать повтор через секунду» почти всегда только усугубляет проблему — сервис снова откажет, а иногда и продлит блокировку за слишком настойчивые попытки. Разберём рабочий порядок действий по шагам.

Шаг 1. Прочитай заголовки ответа

Ответ с кодом 429 почти всегда несёт с собой служебные заголовки (HTTP headers), которые объясняют, что произошло и когда можно пробовать снова. Самые полезные из них:

• Retry-After — сколько секунд подождать перед следующей попыткой. Иногда указан в виде точного числа секунд, иногда как конкретная дата и время.
• X-RateLimit-Limit — сколько запросов разрешено за период.
• X-RateLimit-Remaining — сколько запросов у тебя ещё осталось прямо сейчас.
• X-RateLimit-Reset — когда счётчик лимита обнулится.

Не у всех сервисов набор заголовков одинаковый — конкретные названия и присутствие того или иного заголовка нужно смотреть в документации выбранного API. Но если Claude Code или другой инструмент показывает тебе полный текст ошибки, а не только «что-то пошло не так», в нём часто уже виден этот заголовок или его смысл — например, прямое указание подождать конкретное время.

Шаг 2. Подожди и повтори запрос с нарастающей задержкой

Если сервис не сообщил точное время ожидания через Retry-After, разумная стратегия — не долбить его повторными попытками сразу одну за другой, а постепенно увеличивать паузу между попытками. Этот подход называется экспоненциальный backoff, и суть у него простая: первая повторная попытка — через секунду, если снова отказ — через две секунды, потом через четыре, потом через восемь и так далее. Каждый раз пауза удваивается.

Почему это работает лучше, чем просто «подождать секунду и попробовать снова»: если проблема временная (сервис ненадолго перегружен), короткой паузы может хватить. Но если лимит исчерпан всерьёз — например, дневная квота — быстрые повторные попытки раз в секунду только зря тратят твоё время и множат количество отклонённых запросов. Растущая пауза даёт системе шанс восстановиться, а тебе — не закидывать сервис бессмысленными обращениями.

Хорошие ИИ-инструменты и клиентские библиотеки для работы с API часто уже умеют делать это автоматически — при получении 429 они сами ждут и повторяют запрос по такой схеме, без твоего участия. Если ты пишешь собственный код, который обращается к API напрямую (например, через GitHub Actions), эту логику стоит заложить явно, а не полагаться на удачу.

flowchart TB
    A["Приложение отправляет запрос"] --> B["Сервис возвращает 429"]
    B --> C["Пауза увеличивается: 1с → 2с → 4с"]
    C --> D["Повторный запрос"]
    D -->|"снова 429"| B
    D -->|"успех"| E["Ответ получен"]

На схеме видно: цикл повторяется до тех пор, пока запрос не пройдёт. Важно, чтобы у цикла было ограничение по числу попыток — например, не больше пяти-шести, — иначе при действительно долгой блокировке скрипт будет ждать часами вместо того, чтобы честно сообщить об ошибке и остановиться.

Как это выглядит именно в GitHub Actions. Если внешний API вызывается прямо из шага workflow, растущую задержку приходится закладывать в сам сценарий сборки — GitHub не делает это автоматически за тебя. Практически это означает добавить в шаг простую проверку: если ответ пришёл с кодом 429, workflow ждёт паузу и повторяет запрос, а не падает сразу с ошибкой. Отдельно стоит посмотреть в сторону настройки concurrency у самого workflow: она позволяет автоматически отменять предыдущий незавершённый запуск, если пришёл новый коммит, — тогда серия быстрых коммитов подряд не будет плодить параллельные запуски, каждый из которых дёргает один и тот же внешний сервис.

Шаг 3. Кэшируй повторяющиеся запросы

Кэширование — это сохранение результата запроса, чтобы не спрашивать сервис о том же самом ещё раз. Если твой код или агент несколько раз за сессию запрашивает одну и ту же информацию — например, список файлов в репозитории через GitHub API или ответ модели на один и тот же вопрос, — есть смысл один раз сохранить результат локально и переиспользовать его вместо повторного обращения к API.

Простой пример из практики курса: если ты просишь ИИ несколько раз подряд объяснить одну и ту же ошибку без изменений в коде, каждый раз уходит отдельный запрос к API, хотя ответ, скорее всего, будет одинаковым. Небольшая пауза, чтобы сформулировать вопрос точнее с первого раза, экономит и лимит, и время.

Для GitHub Actions кэширование устроено по-другому: можно сохранять результаты между запусками workflow (сам GitHub предоставляет для этого встроенный механизм кэша), чтобы не запрашивать заново то, что не изменилось с прошлого коммита.

Шаг 4. Объединяй мелкие запросы в один — батчинг

Батчинг — это отправка нескольких операций одним запросом вместо серии отдельных обращений. Не все API это поддерживают, но там, где поддерживают, разница в расходе лимита ощутимая: один запрос на пакет из десяти операций тратит одну единицу лимита вместо десяти.

Применительно к курсу это выглядит так: вместо того чтобы просить ИИ-агента вносить правки в код по одной небольшой команде за раз («поменяй заголовок», потом отдельно «поменяй цвет кнопки», потом отдельно «поправь отступ»), выгоднее сформулировать задачу цельным блоком — «поменяй заголовок, цвет кнопки и отступ» одним сообщением. Меньше отдельных обращений — меньше шансов упереться в лимит частоты запросов.

Шаг 5. Если лимита стабильно не хватает — переходи на платный тариф

Если после кэширования и батчинга лимит всё равно регулярно заканчивается — это не признак того, что ты делаешь что-то неправильно, а сигнал, что бесплатного тарифа объективно недостаточно для объёма твоей работы. У большинства сервисов, включая Claude API, OpenAI API и Gemini API, платные тарифы дают заметно более высокие лимиты, а иногда снимают отдельные виды ограничений совсем. Конкретные условия и цены каждого тарифа смотри на официальном сайте нужного сервиса — они меняются, и приводить здесь цифры не имеет смысла.

Перед тем как платить, стоит убедиться, что причина именно в лимите, а не в неэффективном использовании API — иначе платный тариф лишь отодвинет момент, когда та же проблема повторится на большем масштабе.

Коротко: какой шаг когда применять

Как не доводить дело до ошибки

Пять шагов выше — это что делать, когда лимит уже исчерпан. Но часть проблем проще предотвратить, чем разгребать постфактум.

Следи за оставшимся лимитом, а не только за самой ошибкой. Если сервис присылает заголовок X-RateLimit-Remaining, есть смысл проверять его значение до того, как оно дойдёт до нуля, и заранее притормаживать темп запросов — например, добавлять паузу между действиями агента, если остаток лимита падает ниже условного порога. Это превращает жёсткий отказ в плавное замедление, которое почти не заметно в работе.

Не держи несколько ИИ-агентов на одном ключе одновременно. Если в разных вкладках терминала или на двух устройствах одновременно работают два экземпляра Claude Code с одним и тем же API-ключом, они делят общий лимит пополам, даже не подозревая друг о друге. Со стороны это выглядит как необъяснимое исчерпание лимита при вроде бы умеренной нагрузке — а на деле лимит просто расходуется вдвое быстрее.

Разноси тяжёлую работу по времени. Если знаешь, что задача потребует много обращений к API — например, крупная переработка нескольких файлов сразу, — не запускай её впритык к другой такой же задаче. Небольшой перерыв между тяжёлыми сессиями снижает риск того, что вторая упрётся в остаток лимита от первой.

Проверяй, не запущен ли лишний workflow. В GitHub Actions легко забыть про старый workflow, который продолжает срабатывать на каждый пуш, хотя нужен был только для одной временной задачи. Периодически проверяй список активных workflow в репозитории и отключай те, что больше не нужны — это не только экономит лимит внешнего API, но и ускоряет саму сборку.

Почему нельзя просто «обойти» лимит

Соблазн решить проблему в лоб понятен: создать несколько аккаунтов и распределять запросы между ними, чтобы каждый оставался в рамках своего лимита, или замаскировать один и тот же скрипт под нескольких разных пользователей. Делать так не стоит, и дело не только в риске.

Практически у всех крупных API-сервисов в условиях использования прямо прописан запрет на обход технических ограничений через создание множества аккаунтов, подмену идентификаторов или автоматизацию, имитирующую нескольких разных клиентов. Нарушение этих условий обычно ведёт к блокировке всех связанных аккаунтов разом, а не только того, что превысил лимит. Для проекта, который строится вокруг конкретного API, это означает не отложенную проблему, а полную остановку работы.

Лимиты существуют не как произвольная прихоть сервиса, а как часть инфраструктурной защиты, о которой шла речь в начале статьи. Обход лимита одним пользователем означает, что кто-то другой недополучит доступ к тем же общим ресурсам. Честная стратегия — снижать собственную нагрузку через кэширование и батчинг, ждать с нарастающей задержкой там, где это уместно, и переходить на платный тариф, когда бесплатного объективно не хватает.

Частые вопросы

Что означает ошибка 429 Too Many Requests?

Это стандартный код ответа HTTP, который сервис присылает, когда клиент отправил больше запросов, чем разрешено правилами доступа за выбранный промежуток времени. Сам запрос корректен, проблема исключительно в частоте обращений.

Чем rate limit exceeded отличается от quota exceeded?

Формулировки зависят от конкретного сервиса, но по смыслу обычно разделяют два случая. Rate limit exceeded чаще указывает на превышение частоты запросов за короткий период — минуту или несколько секунд. Quota exceeded чаще говорит об исчерпании общего объёма — токенов, запросов за сутки или выделенного бюджета. Точную трактовку конкретного сообщения смотри в документации сервиса, который его прислал.

Можно ли полностью избавиться от риска упереться в лимит?

Полностью — нет, если ты продолжаешь активно работать с внешним API: у любого тарифа, даже самого дорогого, есть свой потолок. Но можно снизить частоту столкновений с лимитом до минимума за счёт кэширования повторяющихся запросов, объединения мелких операций в одну и аккуратной работы с ИИ-агентом — формулируя задачи цельными блоками, а не бесконечной серией мелких правок.

GitHub Actions пишет ошибку про rate limit — что смотреть в первую очередь?

Сначала открой полный лог упавшего шага workflow и найди, какой именно внешний сервис вернул ошибку — сам GitHub API или сторонний сервис, к которому обращается твой скрипт. У GitHub API и у стороннего ИИ-сервиса разные лимиты и разные условия их сброса, поэтому решение зависит от того, где именно случился отказ.

Стоит ли делать несколько аккаунтов, чтобы обойти лимит?

Нет. Это нарушает условия использования подавляющего большинства API-сервисов и обычно ведёт к блокировке сразу всех связанных аккаунтов, а не только одного. Правильный путь — снижать нагрузку через кэширование и батчинг или переходить на платный тариф с более высоким лимитом.

Как понять, сколько ждать перед повторным запросом?

Если сервис прислал заголовок Retry-After, ориентируйся на него — там указано точное время. Если такого заголовка нет, используй растущую задержку: секунда, две, четыре, восемь, с ограничением на общее число попыток, чтобы скрипт не завис в ожидании на неопределённый срок.

Заключение

Ошибка rate limit exceeded — не поломка и не повод для паники, а часть нормальной работы с любым внешним API. Сервис защищает свою инфраструктуру, а тебе остаётся действовать по понятной схеме: прочитать, что именно ответил сервис, подождать с нарастающей паузой, не спрашивать дважды одно и то же, объединять мелкие запросы и при постоянной нехватке лимита переходить на платный тариф. Если вызовы к Claude API или OpenAI API — часть твоего проекта на постоянной основе, подробнее о работе с этими сервисами читай в статьях про Claude API и про OpenAI API. А если лимит подрезал именно сборку в GitHub Actions, разобраться с автоматическими запусками поможет статья про npm test и CI.