Лимиты¶
Все лимиты API Ziex Try-On, на которые можно наткнуться: значение, что вы получаете при превышении и как реагировать. О форме ответов и правилах повтора — на странице Ошибки.
Три правила покрывают большую часть страницы:
- Каждый
429,409и503, которые формирует API, несётRetry-After(целые секунды). Подождите столько. - Запрос, отклонённый лимитом до появления задачи, ничего не берёт из тарифа, поэтому повтор с тем же
Idempotency-Keyпосле ожидания безопасен. - Сервер, который отправляет запросы всех своих покупателей с одного адреса, делит один бюджет по каждому из
лимитов на адрес ниже. Если вы отправляете примерки со своего сервера за многих покупателей, для API вы — один
адрес: ставьте запросы в очередь и снижайте частоту, иначе получите
429 RATE_LIMITED.
Размер запроса и изображения¶
| Лимит | Значение | При превышении | Что делать |
|---|---|---|---|
| Тело запроса | 12 МБ целиком | 413 PAYLOAD_TOO_LARGE, формируется до того, как запрос дойдёт до API |
Отправляйте фото поменьше. Не повторять без изменений. |
| Одно распакованное изображение | 10 МБ | 422 VALIDATION_ERROR |
Сожмите фото. |
| Размер изображения | до 16 Мп (4096 x 4096 пикселей), не меньше 256 x 256 пикселей | 422 VALIDATION_ERROR |
Уменьшите перед загрузкой. |
| Форматы изображений | JPEG, PNG, WebP, HEIC, AVIF | 422 VALIDATION_ERROR |
Конвертируйте фото. |
| Изображение ссылкой | до 2048 символов, только http или https |
422 VALIDATION_ERROR |
Возьмите ссылку покороче или отправьте изображение загрузкой. |
Слишком крупные изображения сервис сам уменьшает (длинная сторона до 1500 пикселей) перед обработкой, поэтому
отправлять больше примерно 1500 пикселей по длинной стороне нет смысла. Publishable-ключ обязан отправлять фото
покупателя загрузкой (data URI data:), а не ссылкой; одежда может быть ссылкой.
Частота запросов¶
Эти лимиты считаются на адрес клиента, кроме случаев, где назван ключ. Первым их применяет краевой слой; запрос сверх
них получает 429 RATE_LIMITED с Retry-After: 1 и до API не доходит.
| Лимит | Значение | При превышении | Что делать |
|---|---|---|---|
POST /api/v1/tryon, на адрес, на краю |
2 запроса в секунду (2 r/s), всплеск 5 | 429 RATE_LIMITED, Retry-After: 1 |
Разносите отправки хотя бы на полсекунды. |
| Отправки на адрес, в API | 30 в минуту, в фиксированном окне, которое открывает первая отправка (для боевых и тестовых ключей по одному правилу, у каждых свой счётчик) | 429 RATE_LIMITED, Retry-After = остаток окна (не меньше 1 с) |
Подождите. Отклонённая отправка не засчитывается и окно не сдвигает. |
GET /api/v1/tryon/status/{job_id} и GET /api/v1/tryon/attempts/{idempotency_key}, на адрес |
20 запросов в секунду (20 r/s), всплеск 30 | 429 RATE_LIMITED, Retry-After: 1 |
Опрашивайте каждую задачу раз в 1-2 секунды, а не в плотном цикле. |
GET /api/v1/tryon/result/{job_id}, на адрес |
1 запрос в секунду (1 r/s), всплеск 10 | 429 RATE_LIMITED, Retry-After: 1 |
Забирайте результаты по одному и сохраняйте; этот эндпоинт не опрашивайте. |
Все остальные запросы API (capabilities, domain-check, integration, jobs), на адрес |
10 запросов в секунду (10 r/s), всплеск 20 | 429 RATE_LIMITED, Retry-After: 1 |
Кэшируйте GET /api/v1/tryon/capabilities (он публичный и кэшируется на 5 минут). |
GET /api/v1/tryon/jobs, на ключ |
60 запросов в минуту | 429 RATE_LIMITED, Retry-After = остаток окна |
Опрашивайте список раз в минуту, не чаще. |
| Publishable-ключ, на пару (ключ, адрес) | 10 за 10 минут, считаются созданные задачи (у тестового publishable-ключа — 60) | 429 RATE_LIMITED, Retry-After = остаток окна |
Публичный ключ можно скопировать со страницы, поэтому лимит ограничивает расход копии. Обычные покупатели его не достигают. |
Почасовой лимит ключа (rate_limit) |
Задаётся на ключ, по умолчанию 100 в час. Считаются только созданные задачи POST /api/v1/tryon; отклонённые отправки — нет |
429 RATE_LIMITED, Retry-After = остаток часа |
Подождите. Более высокий rate_limit ключа — через обращение к нам (см. Контакты). |
Тариф и дневные потолки¶
| Лимит | Значение | При превышении | Что делать |
|---|---|---|---|
| Квота тарифа | Генерации вашего тарифа за расчётный период; применяется с допуском 10 % (мягкий потолок). Проваленная или прерванная задача возвращает генерацию | 429 LIMIT_EXCEEDED, Retry-After = время до сброса (не меньше 60 с; сутки, если даты сброса нет) |
Повтор до сброса не поможет. Повысьте тариф или подождите. |
| Дневной потолок платформы | Потолок всех генераций платформы за сутки UTC | 429 DAILY_CAP_REACHED, Retry-After = время до ближайшей полуночи UTC |
Не повторять в цикле. Попробуйте после полуночи UTC. |
| Доля одного ключа в дневном потолке | Один ключ, секретный или publishable, может использовать не больше 50 % дневного потолка платформы | 429 DAILY_CAP_REACHED, Retry-After = время до ближайшей полуночи UTC |
То же. Если нужно больше, напишите нам (см. Контакты). |
Дневной потолок защищает каждый аккаунт от утёкшего ключа. Точная цифра дневного потолка платформы в контракт не входит.
Поля запроса¶
| Поле или заголовок | Лимит | При превышении | Что делать |
|---|---|---|---|
Idempotency-Key |
22-64 символа из A-Z a-z 0-9 _ - (^[A-Za-z0-9_-]{22,64}$). Повтор с тем же ключом находит свою задачу, пока она существует (не меньше 24 часов) |
422 VALIDATION_ERROR для неверного ключа |
Берите UUID без дефисов (32 символа). Один ключ на попытку. |
product_title |
Не больше 1000 символов в запросе; хранится обрезанным до 200 символов | 422 VALIDATION_ERROR выше 1000 (ничего не списывается) |
Присылайте короткое название. Более длинное, до 1000, принимается и сокращается. |
product_url |
Не больше 4096 символов в запросе; сохраняется, только если это простая ссылка http или https не длиннее 2048 символов |
422 VALIDATION_ERROR выше 4096; от 2048 до 4096 ссылка отбрасывается (null), а не отклоняется |
Присылайте каноническую ссылку на товар. |
integration |
Не больше 64 символов, в виде name/version (например woocommerce/1.4.0) |
Никогда не отклоняется: неверное значение отбрасывается | Присылайте, как описано, или не присылайте. |
category |
Идентификатор категории из GET /api/v1/tryon/capabilities |
422 CATEGORY_UNSUPPORTED для неизвестной или недоступной |
Читайте список, не зашивайте его в код. |
Обработка и время¶
| Лимит | Значение | При превышении | Что делать |
|---|---|---|---|
| Ожидание свободного слота обработки изображений | До 10 секунд, когда все слоты заняты другими отправками | 503 OVERLOADED, Retry-After: 5, без X-Job-Id. Задачи нет |
Повторите с тем же Idempotency-Key через Retry-After. |
| Время до финального состояния | Каждая задача становится completed, failed или interrupted не позже чем через 45 минут (pending закрывается через 30 минут, processing — через 15) |
Платформа закрывает задачу как проваленную | Через 45 минут перестаньте ждать и прочитайте статус; по такой задаче вебхук может не прийти. |
| Вебхуки | Best effort, срок не гарантируется | Опоздавший или потерянный вебхук | Сверяйтесь опросом GET /api/v1/tryon/status/{job_id} или GET /api/v1/tryon/jobs?since=.... |
| Эндпоинты вебхуков на аккаунт | 10 (live и test вместе) | 409 WEBHOOK_LIMIT (без Retry-After) |
Удалите неиспользуемый эндпоинт, затем создайте новый. |
Тестовые ключи и хранение¶
| Лимит | Значение | При превышении | Что делать |
|---|---|---|---|
| Тестовые ключи на аккаунт | До 3 | 409 TEST_KEY_LIMIT (без Retry-After) |
Удалите один, затем создайте новый. |
| Тестовые отправки на адрес | 30 в минуту для тестового ключа (свой счётчик, такое же фиксированное окно, как у боевого) и 60 за 10 минут для тестового publishable-ключа | 429 RATE_LIMITED |
Подождите Retry-After. |
| Фото и результаты боевых примерок | Хранятся 180 дней, затем удаляются | Файла нет: result_url больше не работает |
Сохраняйте у себя то, что нужно дольше. |
| Файлы тестовых примерок | Хранятся 72 часа, затем удаляются | То же | Тестовый результат — заглушка, хранить нечего. |
Что означает Retry-After¶
| Ответ | Retry-After |
|---|---|
429 RATE_LIMITED от краевого слоя |
1 секунда |
429 RATE_LIMITED от API |
Остаток окна, которое превышено (минута, 10 минут, час), не меньше 1 секунды |
429 LIMIT_EXCEEDED |
Секунды до сброса периода тарифа, не меньше 60; сутки, если даты сброса нет |
429 DAILY_CAP_REACHED |
Секунды до ближайшей полуночи UTC |
409 IDEMPOTENT_IN_PROGRESS |
2 секунды |
503 SUBMIT_UNCONFIRMED |
2 секунды (вместе с X-Job-Id) |
503 ATTEMPT_LOOKUP_UNAVAILABLE |
2 секунды |
503 OVERLOADED |
5 секунд (без X-Job-Id) |
Страница в браузере может прочитать Retry-After, X-Job-Id, Location и X-Request-ID в этих ответах.
Изменение лимита¶
Ослабление документированного лимита — аддитивное изменение и может случиться в любой момент. Ужесточение документированного лимита считается breaking-изменением и анонсируется не позже чем за 90 дней до вступления в силу.