Диагностика и восстановление

Каждый раздел ниже начинается с того, что вы видите, объясняет обычную причину и говорит, что делать. Полное значение каждого номера ошибки — на странице Ошибки и повторы; эта страница отвечает на вопрос «и что теперь?».

Найдите свою проблему

Сохраните полезные сведения

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

• Время — по возможности в UTC.
• Эндпоинт, который вы вызывали, например POST /api/v1/jobs/createTask.
• HTTP-статус и code из тела ответа.
• request_id: он есть в теле ответа и в заголовке ответа X-Request-Id.
• ID задачи, если вы его получили. Он начинается с job_ и виден также на странице Логи в консоли.

Не путайте три ситуации — они требуют разных действий: API явно отклонил запрос (вы получили ошибку в JSON — ничего не создано и ничего не списано), вы вообще не получили ответа (тайм-аут или оборванное соединение — задача может существовать; см. ниже) или задача была принята, а потом завершилась ошибкой (у вас есть ID задачи со state: "failed").

Если ответ не в формате JSON — например, это HTML-страница или обычный текст, — значит, он пришёл от нашей пограничной сети ещё до того, как запрос дошёл до API. Запишите HTTP-статус и первые строки тела. Такая страница с кодом 403 обычно означает, что запрос идёт из региона, который мы не можем обслуживать; повтор ничего не изменит.

Никогда не помещайте API-ключи, пароли, полные промпты или исходные файлы в общие логи или в обращения в поддержку.

Заплатили, а баланс не изменился

• Карта: баланс меняется только после того, как до нас доходит подтверждение от платёжной системы, обычно за несколько секунд. Обновите страницу Биллинг и посмотрите раздел Заявки на пополнение.
• Криптовалюта: деньги зачисляются после того, как сеть подтвердит транзакцию, обычно за несколько минут. Платёж меньше показанной суммы или после истечения страницы оплаты автоматически не зачисляется.
• Ручной перевод: откройте заявку в разделе Заявки на пополнение и отправьте банковский идентификатор платежа или хеш транзакции. Мы проверяем его вручную, обычно в течение нескольких часов.

Полный перечень случаев — в разделе Подготовка аккаунта → Типичные проблемы. Деньги так и не появились? Начните диалог в Поддержке (категория Биллинг) и укажите ID заявки, а для криптовалюты — ещё и хеш транзакции. Никогда не отправляйте номера карт и пароли.

Каждый вызов возвращает 401 или 403

Начните с вызова, который ничего не стоит и ничего не меняет, — с проверки баланса:

echo "${SPICY_API_KEY:0:9}"
curl https://api.spicyapi.ai/api/v1/chat/credit \
  -H "Authorization: Bearer $SPICY_API_KEY"

Первая строка должна вывести sk-spicy-. Если она ничего не выводит, ключ в этом терминале не задан — задайте его снова (см. Подготовка аккаунта). Затем прочитайте msg в ответе:

Ни одна из этих ошибок не исправляется повтором.

Баланс, лимиты и поддержка

• 40201 — доступного баланса не хватает на ориентировочную цену задачи. Пополните баланс (см. Подготовка аккаунта) и отправьте тот же запрос ещё раз с тем же Idempotency-Key. Промоначисление оплачивает только те модели, на которые оно распространяется.
• 40202 — достигнут лимит расходов; какой именно, сказано в msg. Лимит ключа (This key has reached its …) повышается в разделе «Ключи API → Редактировать» или обнуляется сам (дневной — в 00:00 UTC, месячный — 1-го числа, общий — никогда). Лимит команды (Workspace … budget has been reached) повышает на странице «Команда» владелец, администратор или менеджер бюджета. Лимит платформы (Platform quota for today is exhausted…) повысить нельзя; попробуйте снова после 00:00 UTC. См. лимиты расходов.
• 429 — слишком много запросов. Подождите столько секунд, сколько указано в Retry-After, и снизьте темп; больше всего помогает перейти с плотных циклов опроса на вебхуки. Если сообщение — Too many pending uploads…, ожидание не поможет: завершите загрузки, которые уже начали. См. Лимиты запросов.

Обращение в поддержку: начните диалог в разделе Поддержка в консоли или напишите на support@spicyapi.ai. Приложите сведения, о которых сказано выше: время, эндпоинт, code, request_id или ID задачи, что вы ожидали и что произошло, а также структуру вашего запроса без приватных значений. Никогда не отправляйте API-ключ.

Модели нет или она недоступна

• Модели нет в вашем списке, или приходит 404: вызовите GET /api/v1/models со своим API-ключом и используйте модель, у которой и enabled, и available равны true, скопировав её ID в точности. Страница модели на сайте не доказывает, что ваш ключ может вызвать её прямо сейчас. См. Модели и эндпоинты.
• 50301 — модель сейчас не может принимать задачи. Повторите несколько раз с растущими паузами, затем остановитесь: повторные запросы не откроют недоступную модель. Обновите каталог и, прежде чем переходить на другую модель, спросите того, кто платит.
• 40004 — модель работает, но не с таким сочетанием настроек. В msg в скобках названа настройка. Измените её значение (например, разрешение или соотношение сторон), а не повторяйте запрос.
• 40301 — модель существует, но этому ключу пользоваться ею нельзя; отредактируйте список разрешённых моделей ключа.

Некорректные входные данные или конфликт расчёта

• 400 — сравните свой input с текущим inputSchema модели в каталоге: имена полей, типы, допустимые значения и условные требования. Уберите поля, которых нет в списке модели. После смены модели проверьте снова, потому что у каждой модели своя схема.
• 40003 — загруженный файл не соответствует тому, что вы заявили, запрашивая URL для загрузки. Запросите новый URL для загрузки с правильными contentType и размером и загрузите файл снова.
• 413 — тело запроса слишком большое. Загружайте медиа через процесс загрузки, а не встраивайте их в запрос.
• 40901 — срок расчёта истёк, запрос изменился после расчёта или изменилась цена. Получите новый расчёт, покажите новую сумму тому, кто платит, и подтвердите снова. См. Расчёт цены и совместимость.
• Другие 409 — действуйте в зависимости от операции. Если ключ идемпотентности уже использован для другого тела запроса, новому запросу нужен новый, правильный Idempotency-Key, а не бесконечные повторы. См. Ошибки и повторы → когда стоит повторять 409.

Отправка завершилась по тайм-ауту без ID задачи

Тайм-аут не говорит, была ли задача создана. Не отправляйте запрос заново с новым ключом идемпотентности — так может появиться вторая задача и второе списание.

Тайм-ауты на стороне клиента, закрытые вкладки браузера и оборванные потоки не отменяют принятую задачу, а принятую задачу отменить нельзя.

Задача завершилась ошибкой

При ошибке или истечении срока задачи резерв обычно освобождается полностью. Некоторые отказы по содержанию оплачиваются по принятой цене, только если это исключение прямо указано на странице модели. Окончательную сумму проверяйте по settled и cost.

• Не повторяйте без изменений: invalid_request, unsupported_combination, content_rejected (выбранная модель отклонила содержимое — измените промпт или модель).
• Стоит повторить после паузы: rate_limited, upstream_unavailable, upstream_failed.
• Сначала исправьте: invalid_asset (загрузите файл заново), timeout (попробуйте меньшую длительность или более низкое разрешение), generation_failed (с теми же входными данными задача обычно завершается той же ошибкой).

errorMessage объясняет причину для людей; это может быть собственное объяснение модели на английском. Ветвите логику кода только по errorCode. Полная таблица — на странице Ошибки и повторы. Повтор — это новая задача, и в случае успеха она оплачивается заново.

Задача долго в queued или running

Генерация требует времени — длинное видео может создаваться несколько минут. У каждой задачи есть крайний срок на стороне сервера, который recordInfo возвращает в поле deadlineAt:

• До deadlineAt: продолжайте ждать обратного вызова или опрашивайте recordInfo с растущими паузами (не каждую секунду).
• После крайнего срока: задача сама завершается в состоянии expired с errorCode: "timeout", и её резерв возвращается полностью. Ничего отменять не нужно — да и принятые задачи отменить нельзя.

Если задача остаётся в running намного дольше своего deadlineAt, обратитесь в поддержку и укажите ID задачи.

Загрузка прошла, но входные данные отклонены

• Вы пропустили подтверждение (commit). Успешного PUT файла недостаточно: вызовите files/{fileId}/commit, а затем передайте полученный URI spicy:// в поле входных данных модели. Никогда не передавайте сам uploadUrl.
• Файл не соответствует билету. Проверьте заявленные Content-Type, размер и формат; при несоответствии возвращается 40003.
• Срок действия истёк. Загруженным файлом можно пользоваться до expiresAt из ответа на commit — по умолчанию 1 день или меньше, если в вашем аккаунте загрузки удаляются по завершении задачи. Поэтому для повтора задачи может понадобиться загрузить файл заново.
• Файл принадлежит другому аккаунту. URI spicy:// работает только с ключами того аккаунта, который загрузил файл.

Полный процесс загрузки описан на странице Загрузка медиа и результатов.

Нет обратного вызова или истекла ссылка на скачивание

Обратный вызов не пришёл:

1. Проверьте, что callBackUrl — адрес https://, доступный из интернета. Обычный http:// не принимается.
2. Проверьте, что ваш обработчик проверяет подпись по исходным байтам запроса, до разбора JSON, и быстро отвечает статусом 2xx. Долгую работу выполняйте в собственной очереди. Если ключ подписи недавно меняли, обработчик должен пользоваться новым: переходного периода нет. См. Webhook.
3. Посмотрите историю доставок на странице Вебхуки в консоли — там же доставку можно повторить.
4. А пока прочитайте задачу через recordInfo — опрос всегда остаётся рабочим запасным вариантом. См. Webhook.

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

Пропала ссылка на скачивание или сам файл:

• Ссылка на скачивание действует 20 минут. Если результат ещё хранится, просто запросите новую ссылку; обновлять старую бесполезно.
• Если результат ещё копируется в хранилище, подождите несколько секунд и запросите снова.
• Результаты хранятся не дольше примерно 14 дней, а если в вашем аккаунте задан более короткий срок хранения — меньше. Когда contentState равен expired или purged, файл восстановить нельзя — запустите модель заново. См. Хранение и удаление данных.

Поток обрывается раньше времени

Прежде чем разбирать поток по правилам своего протокола, проверьте HTTP-статус и Content-Type. Сетевые фрагменты — это не целые события, а закрытое соединение — не признак успеха: ищите финальное событие протокола, события ошибок и учитывайте собственный крайний срок приложения. Не считайте, что оборванный поток был бесплатным или его можно отправить заново без затрат: действительный расход, учтённый до обрыва, может быть оплачен. Сохраните request_id и проверьте свои записи о расходах. См. Текст и потоковые ответы.

Права в команде

• Не получается создать ключ. Переключатель области вверху левой боковой панели консоли установлен на команду, где у вас роль «Менеджер бюджета» или «Только чтение». Для создания ключей нужна роль «Владелец», «Администратор» или «Разработчик». Переключитесь на личную область или попросите администратора команды дать вам роль «Разработчик».
• Задачу видно, а её промпт или результат — нет. Менеджеры бюджета и участники с ролью «Только чтение» видят только статус, стоимость и расход.
• Не получается принять приглашение. Войдите с тем самым адресом почты, на который отправлено приглашение. Приглашения истекают через 7 дней; если ваше истекло, попросите новое.
• Ключ команды остановился с кодом 40201. Ключи команды тратят баланс владельца команды, поэтому пополнить баланс должен владелец.

Роли и лимиты команд описаны на странице Консоль и команды.

Не получается выписать счёт

• Реквизиты заполнены не полностью. Для счёта нужны имя (название вашей организации или ваше собственное), первая строка адреса, город и страна — их один раз вводят вверху раздела Биллинг → Счета.
• Символ нельзя напечатать. В счёте могут быть только латиница, греческий алфавит и кириллица. Название японской или корейской компании пишите в его зарегистрированной латинской транскрипции.
• Счёт уже существует. На каждое оплаченное пополнение и на каждый закрытый месяц счёт можно выписать один раз; скачайте уже выписанный документ. Чтобы исправить реквизиты, нажмите у него Выписать заново.
• Месяц недоступен. Выписку о расходах можно получить только за закончившийся месяц, в котором вы что-то потратили.

См. Оплата → счета и выписки о расходах.

Связанные разделы

Ошибки и повторы · Интеграция в рабочей среде · Идемпотентность · Загрузка медиа и результатов · Webhook · Текст и потоковые ответы · Подготовка аккаунта