Коды ошибок

Все ошибки API приходят в одном конверте:

{
  "error": {
    "code": "insufficient_funds",
    "message": "не хватает дублонов: нужно 150, на балансе 100"
  }
}

code — машинная строка, на неё и ветвимся в коде. message — для человека, формат не гарантирован, парсить не надо.

Таблица кодов

HTTP	code	Что значит	Что делать
400	bad_request	Кривой запрос в целом	Проверить тело и заголовки
401	unauthorized	Ключ отсутствует, неверен или отозван	Перевыпустить ключ: /apikey в боте
402	insufficient_funds	Не хватает дублонов на заказ	Пополнить баланс в боте; проверить GET /balance
403	forbidden	Доступ запрещён	Проверить, что зовёшь своим ключом свои ресурсы
404	not_found	Нет такого заказа, вебхука, канала или файла	Проверить id; чужие ресурсы тоже отвечают 404; файлы заказа живут 30 дней
409	fair_use_exceeded	Исчерпан fair-use лимит тарифа (тяжёлые ролики)	Дождаться нового месяца или заказывать за дублоны
409	not_awaiting_review	Заказ не ждёт ревью сценария	Ревью возможно только в статусе awaiting_review
409	idempotency_conflict	Idempotency-Key уже использован другим аккаунтом	Сгенерировать свой уникальный ключ
410	gone	Промокод истёк или исчерпан	Запросить новый код
422	invalid_params	Тело не прошло валидацию	message указывает поле и причину
429	rate_limited	Больше 30 POST в минуту на ключ (или почасовой лимит suggest/мастер-промпта)	Притормозить, ждать Retry-After
429	active_tasks_exceeded	Уже 10 активных задач (queued+running; ролики и нарезки вместе)	Дождаться done/error, ждать Retry-After
500	internal_error	Что-то сломалось у нас	Ретрай с backoff; если повторяется — поддержка
502	generator_unavailable	Генератор временно недоступен	Ретрай с backoff
503	service_unavailable	Сервис на обслуживании (в т.ч. глобальный дневной лимит suggest)	Ретрай с backoff

Частые 422:

• cta: true несовместим с cta_target_type/cta_target/cta_word/cta_limit — это два разных режима: простой CTA (cta + обязательный placement) и целевой (без cta, cta_target = @хэндл бота или URL сайта, опционально cta_word/cta_limit).
• bg_preset принимает только id из живого каталога GET /public/v1/bg-presets — имена не угадываются.
• Источники контента и фона взаимоисключающие: theme_url vs theme; из bg_ai/bg_preset/bg_url/bg_asset_id — только один.
• Нарезка: нужен ровно один источник — source_url ИЛИ source_asset_id; smart_crop требует split_layout: 33; split_layout — только 0/33/50/60.
• Канал: schedule_enabled: true требует schedule_hour и непустой schedule_days (числа 0–6, Пн–Вс).

Лимиты и Retry-After

На ключ действуют два лимита: 10 активных задач (queued + running; с 0.87.0 в эту квоту входят и нарезки — ролики и клипы вместе) и 30 POST в минуту. Превышение — 429 с заголовком Retry-After (секунды до следующей попытки). Уважай его: это дешевле, чем гадать.

Правила хорошего тона

• Idempotency-Key на все POST /videos, /videos:quick и обязательно на /clips — ретраи клиента не должны двоить списания. Повтор с тем же ключом в течение 24 часов возвращает исходную задачу (200 вместо 201).
• Ретраи GET — с экспоненциальным backoff и jitter, на 429/5xx — по Retry-After.
• Ошибка генерации — не HTTP-ошибка: смотри status заказа. refunded — дублоны уже возвращены на баланс автоматически (как в боте), error — сбой без списания (триал или внешняя оплата).

Поддержка: @piratepress_support.