Коды ошибок

Все ошибки 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; файлы заказа живут 30 дней
409	fair_use_exceeded	Исчерпан fair-use лимит тарифа (тяжёлые ролики)	Дождаться нового месяца или заказывать за дублоны
409	not_awaiting_review	Заказ не ждёт ревью сценария	Ревью возможно только в статусе awaiting_review
422	invalid_params	Тело не прошло валидацию	message указывает поле и причину
429	rate_limited	Больше 30 POST в минуту на ключ	Притормозить, ждать Retry-After
429	active_tasks_exceeded	Уже 10 активных задач (queued+running)	Дождаться done/error, ждать Retry-After
500	internal_error	Что-то сломалось у нас	Ретрай с backoff; если повторяется — поддержка
502	generator_unavailable	Генератор временно недоступен	Ретрай с backoff
503	service_unavailable	Сервис на обслуживании	Ретрай с backoff

Лимиты и Retry-After

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

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

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

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