WaveSpeedAI

WaveSpeed API Аутентификация и обработка ошибок: исправляем 401, 429, 5xx как профессионалы

WaveSpeed API Аутентификация и обработка ошибок: исправляем 401, 429, 5xx как профессионалы

Привет, я Дора—я ломаю API для того, чтобы вы этого не делали.

На прошлой неделе я постоянно получал ошибки 401. Не того загадочного типа—того глупого типа, когда ты знаешь, что что-то не так, но не видишь что именно. Оказалось, я использовал X-API-Key в своих заголовках. WaveSpeed хочет Authorization: Bearer. Маленькое отличие. Два впустую потраченных часа.

В этом и суть аутентификации API—она работает молчаливо, когда всё правильно, и шумно падает, когда нет. И WaveSpeed, как большинство современных API, не даёт вам особых свобод. Это то, что я узнал, используя WaveSpeed API для генерации изображений и видео в течение последних нескольких месяцев—и что действительно помогло, когда всё сломалось.

Как на самом деле работает аутентификация WaveSpeed API

WaveSpeed использует аутентификацию Bearer-токена. Каждый запрос требует:

  • Authorization: Bearer <YOUR_API_KEY>
  • Content-Type: application/json

Формат простой:

Authorization: Bearer your_api_key_here
Content-Type: application/json

Я видел, как люди пробуют X-API-Key, Api-Key или заключают его в кавычки. Официальная документация WaveSpeed и примеры последовательно показывают формат Bearer-токена. И всё. Никаких вариаций.

Получение вашего API ключа

Ваш API ключ находится в панели управления WaveSpeed на wavespeed.ai/accesskey. Вам нужно пополнить свой счет перед тем, как вы сможете создать ключ—нет ключей для пользователей бесплатного уровня.
Когда вы копируете ключ, следите за лишними пробелами. Я сделал это дважды—скопировал пробел в конце и потратил 20 минут на отладку, прежде чем заметил.

Поток аутентификации для WaveSpeed API

Нет обновления токена, нет OAuth, нет промежуточных шагов. Вы отправляете Bearer-токен, WaveSpeed его проверяет, ваш запрос либо выполняется, либо отклоняется с ошибкой 401.
Если аутентификация не удаётся, вы сразу же получаете ответ 401. Ошибка обычно говорит “invalid authentication” и просит вас проверить ключ.

Обработка ошибок 401 Unauthorized

401 от WaveSpeed означает, что он посмотрел на ваш заголовок Authorization и сказал “Я это не узнаю.”

Контрольный список частых причин

Обычные подозреваемые:

  • Неправильный формат заголовка (не используется Authorization: Bearer)
  • API ключ скопирован с пробелами или переводами строк в конце
  • Ключ пересоздан в панели управления, но старый ключ всё ещё в коде
  • Переменная среды не загружается
  • Счет не пополнен—ключи не создаются без добавления кредитов сначала

Быстрые исправления

Когда я получаю 401, я начинаю отсюда:
Сначала логирую точный заголовок. Не то, что я думаю, что отправляю—что на самом деле в HTTP-запросе. Часто Bearer-токен деформирован или имя заголовка немного отличается.
Во-вторых, копирую ключ заново из панели управления. Тестирую его сразу же с помощью curl перед тем, как поместить в код:

curl -X POST "https://api.wavespeed.ai/api/v3/wavespeed-ai/flux-dev" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "test"}'

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

Управление ответами 429 Rate Limit

Ограничения скорости WaveSpeed являются уровневыми: Bronze (базовые ограничения, пополнение на $100), Silver (более высокая параллельность, пополнение на $1,000) и Gold (пользовательский, $10,000+). Каждый уровень имеет различные пропускную способность и лимиты одновременных задач.

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

Понимание ограничений скорости

Согласно FAQ, примеры ограничений включают Bronze с 10 изображениями / 5 видео в минуту с максимум 3 одновременными задачами, Silver с 500 изображениями / 60 видео в минуту с максимум 100 одновременными и **Gold с 2000 изображениями / 120 видео в минуту с максимум 200 одновременными.

Если вы получаете ошибки “Too Many Requests”, вы, вероятно, достигли ограничения вашего уровня. Чтобы избежать дросселирования, рассмотрите возможность обновления вашего плана.

Стратегия экспоненциального отката для повторных попыток

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

  • Первая повторная попытка: ждать 1 секунду
  • Вторая повторная попытка: ждать 2 секунды
  • Третья повторная попытка: ждать 4 секунды
  • После трёх попыток остановитесь и логируйте отказ

Многие API включают заголовок Retry-After, который точно сообщает, как долго ждать. Проверьте его и используйте это значение, если оно доступно.

Проектирование очереди запросов на стороне клиента

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

  • Отслеживаю, сколько запросов я отправил в текущем временном окне
  • Когда я приближаюсь к лимиту (скажем, 90% пропускной способности моего уровня), паузирую новые запросы
  • Возобновляю, когда временное окно сбрасывается

Это предотвращает большинство 429 до того, как они случаются. Я всё ещё получаю их иногда, когда несколько процессов работают одновременно, но логика повторных попыток их обрабатывает.

Работа с ошибками 5xx Server

Ошибки сервера отличаются. 401 или 429 — это я что-то делаю неправильно. 500 или 503 от WaveSpeed означает, что что-то сломалось с их стороны.

Безопасные шаблоны повторных попыток

Для ошибок 5xx безопасно повторять попытку—большинство ошибок сервера разрешаются в течение нескольких секунд. Хороший шаблон из документации Microsoft — повторить попытку немедленно один раз на случай, если это временная ошибка, а затем вернуться к экспоненциальному откату, если она сохраняется.

Мой подход:

  • Повторить попытку немедленно один раз (может быть, это был сбой)
  • Если это не сработает, используйте тот же экспоненциальный откат, что и для 429
  • Ограничьте три попытки в сумме
  • Логируйте отказ и двигайтесь дальше

Для GET запросов (проверка статуса генерации) повтор всегда безопасен.
Для POST запросов (запуск новой генерации) я более осторожен—я не хочу случайно запустить одну и ту же работу дважды.

Эффективное настройка таймаутов

Я установил два таймаута:

  • Таймаут соединения: 5 секунд
  • Таймаут чтения: 30 секунд

WaveSpeed нацелен на “менее 2 секунд” для изображений и “около 2 минут” для видео, хотя фактические времена зависят от модели, разрешения и нагрузки.

Большинство генераций изображений завершаются менее чем за 5 секунд. Видео занимает больше времени—иногда 60–90 секунд. Но я видел случайные скачки к 20+ секундам даже для изображений.

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

Логирование и наблюдаемость в WaveSpeed API

Когда аутентификация и обработка ошибок заработали, мне нужно было знать, что они продолжают работать.

Что логировать

Для каждого вызова WaveSpeed API я логирую:

  • Конечную точку модели которая вызывается
  • Код статуса HTTP
  • Время отклика в миллисекундах
  • Была ли это повторная попытка и номер какой попытки

При обращении в поддержку WaveSpeed по поводу неудачных запросов они просят ID работ и временные метки. Сохраняйте их в своих логах для отладки.

Пороги оповещений

Я установил оповещения для:

  • Частота ошибок 401 выше 1% (аутентификация сломана)
  • Частота ошибок 429 выше 5% (постоянно достигаются ограничения скорости)
  • Любые ошибки 5xx (должны быть редкими)
  • Среднее время отклика выше 10 секунд (потенциальные проблемы с производительностью)

Это не универсальные пороги—они имели смысл для моего использования. Важно иметь какой-то порог, который запускает расследование, прежде чем пользователи это заметят.

Контрольный список продакшена для аутентификации WaveSpeed API

Перед выходом в продакшен:

  • API ключи хранятся в переменных среды, не в коде
  • Используется правильно формат Authorization: Bearer
  • Заголовок Content-Type установлен на application/json
  • Логика повторных попыток с экспоненциальным откатом для 429 и 5xx
  • Таймауты настроены (5 секунд соединение, 30 секунд чтение)
  • Логирование включает коды статуса, время отклика, ID работ
  • Оповещения установлены для скачков частоты ошибок
  • Ограничение скорости на стороне клиента, чтобы остаться в пределах лимитов уровня
  • Мониторинг баланса интегрирован для отслеживания использования кредитов

Я всё ещё получаю 429 иногда во время скачков трафика. И я видел несколько ошибок 5xx, когда у WaveSpeed были кратковременные проблемы в прошлом месяце. Но с этой установкой эти ошибки не каскадируют.

Аутентификация в основном работает просто тем, что работает. Усилие идёт на обработку раз, когда это не так—чисто, предсказуемо, без того, чтобы разбудить меня в 2 часа ночи, потому что баланс кредитов упал до нуля.

💡 Сталкиваетесь с проблемой?
Опубликуйте код ошибки + ID запроса в комментариях, и мы проведём вас через контрольный список устранения неполадок, чтобы помочь выявить основную причину.

**Совет: Большинство ошибок возникают на клиентской стороне и контролируются (заголовки, API ключ, ограничения скорости), но этот процесс также помогает вам обнаружить проблемы, которые требуют поддержки WaveSpeed.