Почему Groq API возвращает 429 и как читать rate-limit headers

Перед внедрением откройте страницы Models и Limits своей организации. Модельный каталог и персональные квоты меняются, поэтому статья не подменяет живую проверку. Зафиксируйте model id, версию SDK и контрольный вход в журнале теста.

Подтвержденные факты

• Лимиты включают RPM, RPD, TPM, TPD, а для аудио ASH и ASD.
• Некоторые организации имеют отдельные ITPM и OTPM.
• Лимиты применяются на уровне организации.
• При 429 появляется retry-after; остальные rate-limit headers присутствуют постоянно.

Groq использует OpenAI-подобную структуру Chat Completions: массив messages, выбранную model, choices, finish_reason и usage. При этом совместимость не означает равенство всех параметров. Проверяйте документацию конкретной возможности и не отправляйте неизвестные поля «на всякий случай».

Пошаговая настройка

1. Сформулируйте машинный критерий: точная строка, валидная JSON Schema, допустимый tool call или определенный HTTP-код. Субъективное «ответ нормальный» не подходит.
2. Создайте отдельный ключ для dev/stage/prod и храните его как GROQ_API_KEY на backend. Не включайте Authorization в логи, браузерный bundle и репозиторий.
3. Скопируйте актуальный model id из Groq Console и проверьте поддержку нужной функции. Возможность Chat Completion не гарантирует structured output, reasoning или кэш.
4. Выполните минимальный пример ниже. На первом прогоне отключите собственные retry и middleware, чтобы увидеть исходный HTTP-код и тело ошибки.
5. Сравните ответ с условием: При 429 запрос не повторяется немедленно всеми worker: учитывается retry-after и jitter, очередь замедляется, а метрики показывают конкретно исчерпанный ресурс.
6. Проведите отрицательный тест: неподдерживаемый параметр, невалидные аргументы, испорченная строка JSONL или искусственный 429/498. Ошибка должна обрабатываться явно.
7. Затем добавьте ограниченные повторы, jitter, таймаут и метрики. Не повторяйте 400; исправляйте тело. Для 429 уважайте retry-after, для Flex отдельно обрабатывайте 498.

Рабочий пример

def wait_after_429(response, attempt):
    if response.status_code != 429: return 0
    server=float(response.headers.get("retry-after", "1"))
    return min(60, server + random.uniform(0, min(5, 2**attempt)))
# До отправки также ограничивайте очередь по RPM и оцененным input tokens.

Значения в угловых скобках требуют замены на идентификаторы из актуальной документации. Пример намеренно не содержит настоящего ключа. Код бизнес-функций и хранилищ также должен иметь собственную авторизацию — модель не является системой контроля доступа.

Готовый промпт для проверки

Ты инженер приемки Groq API. Проверь приложенные request и response для сценария «почему Groq API возвращает 429».
Верни таблицу: проверка | фактическое значение | PASS/FAIL | исправление.
Обязательно проверь HTTP-код, model, finish_reason, usage и условие результата.
Не восстанавливай отсутствующие поля и не считай HTTP 200 достаточным.

Перед передачей логов удалите ключ, персональные данные и лишний prompt. Решение о PASS принимает код по заданным правилам; языковая модель может только помочь найти несоответствия.

Контрольный вход и ожидаемый результат

Контрольный вход встроен в пример. Сохраните точные messages, model id и параметры. Сначала выполните пять одинаковых запросов, затем меняйте ровно один параметр. Это отделяет случайность генерации от ошибки конфигурации.

Ожидаемый результат: При 429 запрос не повторяется немедленно всеми worker: учитывается retry-after и jitter, очередь замедляется, а метрики показывают конкретно исчерпанный ресурс.

HTTP 200 подтверждает транспорт, но не формат и смысл. Проверяйте choices, finish_reason, непустой content, JSON Schema, аргументы инструментов или полноту batch-результатов. Отсутствующее поле нельзя молча заменять нулем: это скроет обрыв streaming или изменение SDK.

Критерии приемки

• headers логируются
• retry-after соблюден
• число retry ограничено
• очередь имеет backpressure
• лимиты берутся из аккаунта