Ошибки и ограничения

Ошибки запроса возвращают HTTP-статус, отличный от 2xx, и конверт с ошибкой:

{
  "code": 402,
  "error": {
    "message": "Insufficient balance. Please top up your account",
    "type": "PaymentRequired",
    "code": "insufficient_balance"
  }
}

Разветвляйтесь по статусу HTTP и error.code, а не по английскому сообщению.

HTTP	Общий код	Действие
400	`invalid_input`	Исправьте идентификатор модели, поля, значения или условные требования.
401	`api_key_missing`, `api_key_invalid`	Отправьте действительный API-ключ.
402	`insufficient_balance`	Пополните баланс перед повторной попыткой. Задача не была создана.
404	`task_not_found`, `generation_not_found`	Проверьте идентификатор и аккаунт владельца.
429	`unknown_error`	Сделайте паузу и повторите попытку с джиттером.
500, 503	`unknown_error`	Повторите ограниченное количество раз с экспоненциальной задержкой.

Неудавшиеся задачи

Медиа-запрос может быть принят, но позднее завершиться ошибкой. Эндпоинт статуса по-прежнему вернёт HTTP 200, однако data.status будет равен failed, а data.errorMessage будет содержать безопасное объяснение. Списанная сумма возвращается автоматически.

Не отправляйте повторную платную генерацию только потому, что опрос идет медленно. Повторяйте попытку только после завершения исходной задачи.

Ограничения по скорости

Для всех эндпоинтов /api/v1 действует общее ограничение: 120 запросов в минуту. Окно скользящее и длится 60 секунд, а счётчик привязан к IP-адресу, не к API-ключу. Несколько ключей с одного адреса используют общий лимит; счётчик также общий для всех реплик API.

Ограничение касается только объема запросов. Это не квота на генерации, на параллельные задачи или на расходы; сколько вы можете сгенерировать, определяется вашим предоплаченным балансом, а ожидающая в очереди генерация не требует дополнительных затрат во время выполнения.

Чтение заголовков

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

Заголовок	Значение
`X-RateLimit-Limit`	Запросы, разрешенные в окне (`120`).
`X-RateLimit-Remaining`	Рекомендованное количество оставшихся запросов до достижения лимита.
`X-RateLimit-Reset`	Секунды до сброса окна и обнуления счёта.
`Retry-After`	Отправляется только при `429`: секунды, которые нужно ждать перед повторной попыткой.

curl -sS -D - -o /dev/null https://api.api-stock.com/api/v1/catalog

HTTP/2 200
x-ratelimit-limit: 120
x-ratelimit-remaining: 119
x-ratelimit-reset: 60

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

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

121-й запрос в том же скользящем 60-секундном окне возвращает HTTP 429 со стандартным объектом ошибки и заголовком Retry-After:

{
  "code": 429,
  "error": {
    "message": "ThrottlerException: Too Many Requests",
    "type": "Error",
    "code": "unknown_error"
  }
}

Ветвиться по HTTP-статусу. Ничего не было создано и ничего не было списано, поэтому запрос безопасно повторить после того, как пройдет Retry-After секунд.

Пребывание в пределах лимита

Опросы на практике истощают бюджет — флот рабочих, запрашивающих статус задачи каждую секунду, достигает 120 запросов в минуту при двух выполняющихся задачах. В порядке эффективности:

Используйте вебхуки. Передайте webhook на generation/create, и завершённая задача будет доставлена вам. Это полностью устраняет опрос статуса и является самым большим сокращением объёма запросов.
Делайте паузу при опросе. Подождите 5–10 секунд перед первой проверкой статуса, затем увеличивайте интервал до 30 секунд. Генерация видео занимает минуты; опрашивать его каждую секунду бесполезно.
Опрос одного задания за запрос. Ведите собственный учёт группами вместо повторной проверки каждой задачи в вашей очереди на каждом шаге.
Останавливайтесь на финальном статусе. finished, failed и expired больше не меняются.

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

Повторные попытки и откат

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

Повторяйте запросы после 429, сбоев соединения, 500 и 503, ограничивая число попыток.
Не повторяйте 400, 401, 402 или 404 без изменений — результат будет таким же, пока сам запрос не изменится.
Сначала проверьте результат вызова создания задачи, истёкшего по тайм-ауту, и только затем отправляйте новую генерацию. Сервер мог принять и списать такой запрос; проверьте список задач, чтобы не платить повторно.