IskraGen

Errors

Формат ошибок и список кодов

Все ошибки API возвращаются в едином формате с HTTP-статусом ≥ 400:

{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Недостаточно средств на балансе",
    "requestId": "req_01HX5Y3KJ8...",
    "timestamp": "2026-04-30T12:00:42.123Z"
  }
}

requestId — идентификатор запроса для саппорта. Сохраняйте его в логах: с ним мы быстрее найдём проблему.

HTTP-статусы

КодЧто означает
400 Bad RequestНеверные параметры запроса (см. code)
401 UnauthorizedНет действующего API-ключа или сессии кабинета
403 ForbiddenАвторизация пройдена, но нет прав на ресурс
404 Not FoundРесурс не существует или принадлежит другому пользователю
402 Payment RequiredБаланса не хватает на стоимость запроса
409 ConflictКонфликт состояния (например, уже выполняется идемпотентный запрос)
410 GoneМодель снята провайдером — повтор не поможет
429 Too Many RequestsПревышен лимит — см. Rate limits
500 Internal Server ErrorВнутренняя ошибка
502 Bad GatewayПровайдер модели недоступен
503 Service UnavailableСервис временно недоступен или в maintenance

Коды ошибок (error.code)

Аутентификация и авторизация

  • AUTHENTICATION_ERROR (401) — нет действующего API-ключа или сессии кабинета: ключ отсутствует, невалиден или отозван, сессия истекла.
  • AUTHORIZATION_ERROR (403) — авторизация пройдена, но прав на ресурс нет.

Валидация

  • VALIDATION_ERROR (400) — параметры не прошли схему. Разбор — в error.details.fields[], по одному элементу на нарушение:
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "body must have required property 'modelSlug'",
    "details": {
      "fields": [
        {
          "path": "body",
          "keyword": "required",
          "message": "must have required property 'modelSlug'",
          "params": { "missingProperty": "modelSlug" }
        }
      ]
    },
    "requestId": "…",
    "timestamp": "…"
  }
}
  • NOT_FOUND (404) — ресурс не существует, недоступен или принадлежит другому пользователю. Этим же кодом отвечает несуществующий modelSlug.
  • MODEL_NOT_AVAILABLE (403) — модель выключена или недоступна вашему аккаунту.
  • MODEL_UNAVAILABLE (410) — провайдер снял модель. Повтор не поможет, выберите другую.
  • UNSUPPORTED_MEDIA_TYPE (415) / PAYLOAD_TOO_LARGE (413) — отказ на уровне HTTP-тела запроса: неверный Content-Type или тело больше лимита сервера. Слишком большой файл или неподдерживаемый тип файла в POST /v1/files возвращают VALIDATION_ERROR (400).

Биллинг

  • INSUFFICIENT_BALANCE (402) — баланс ниже стоимости запроса. В error.details — required и available.
  • MARGIN_GUARD (503) — цена модели для этого запроса ниже допустимого минимума относительно себестоимости провайдера. Генерация не создаётся, деньги не списываются. Это ошибка конфигурации на нашей стороне: повтор не поможет, напишите в поддержку.
  • VALIDATION_ERROR (400) с сообщением Model pricing not configured — цена модели не настроена.
  • PAYMENT_ERROR (502) — сбой платёжного контура.
  • RESERVATION_EXPIRED (409) — резерв средств истёк до подтверждения.

Лимиты

  • RATE_LIMIT_ERROR (429) — превышен лимит запросов либо число одновременных генераций (по умолчанию 5). Для лимитов с окном время до повтора указано в error.details.retryAfter и заголовке retry-after; у лимита одновременных генераций этих полей нет.
  • DAILY_CAP_EXCEEDED (429) — исчерпан суточный лимит пополнений.

Конфликты состояния

  • CONFLICT_ERROR (409) — конфликт состояния.
  • MODERATION_REPEAT_BLOCKED (409) — запросы к этой модели остановлены, потому что подряд идущие попытки отклонены её проверкой безопасности; повтор без изменения материала не поможет — измените материал или выберите другую модель. В error.details поле modelSlug содержит публичный идентификатор модели, modelId устарело и сохранено для совместимости, streak содержит длину серии отказов.

Повтор с тем же idempotencyKey (в теле или в заголовке Idempotency-Key) в пределах одного пользователя и с тем же телом запроса возвращает уже существующую генерацию (id, status, costRub), не создаёт новую и не списывает деньги второй раз — даже если тело уже не проходит проверку параметров модели. Если тело отличается от исходного (модель, prompt, параметры, размеры, длительность, seed, pricingVersion, expectedCostRub, quoteId), ответ — IDEMPOTENCY_KEY_REUSED (409), деньги не списываются; для нового запроса нужен новый ключ. maxCostRub в сравнении не участвует. Генерации, созданные до появления этой проверки, возвращаются без сравнения тела. Отказы, которые срабатывают раньше поиска по ключу, остаются отказами: например, AUTHENTICATION_ERROR (401) без действующей авторизации и VALIDATION_ERROR (400) при нарушении схемы запроса, например durationSec: 601. Полный список — в Generations API.

Нарушение правил сервиса

  • CONTENT_POLICY_VIOLATION (422) — запрос нарушает правила сервиса. Деньги не списаны.

Провайдер и внутренние интеграции

  • PROVIDER_ERROR (502) — общая ошибка провайдера модели.
  • UPSTREAM_CIRCUIT_OPEN (503) — приём генераций на модели временно остановлен на нашей стороне, деньги не списаны; повтор сразу не поможет — выберите другую модель или попробуйте позже.
  • SUNO_MODE_UNAVAILABLE (503) — этот режим Suno временно недоступен, деньги не списаны. Выберите другой режим или попробуйте позже.
  • SERVICE_UNAVAILABLE (503) — внешняя зависимость временно недоступна.
  • OUTPUT_FETCH_FAILED (502) — файл результата не удалось получить из хранилища.
  • GATEWAY_CLIENT_ERROR (502) — внутренняя интеграция получила ошибку запроса от Media Gateway.
  • WEBHOOK_DELIVERY_ERROR (502) — доставка webhook завершилась ошибкой.
  • TELEGRAM_NOT_CONFIGURED (409) — Telegram-бот не настроен для запрошенной операции.
  • INTERNAL_ERROR (500) — внутренняя ошибка.
  • GATEWAY_*, BILLING_* (502/503) — сбой внутренней интеграции. Повторите запрос с экспоненциальной задержкой; код нужен саппорту, самостоятельно обрабатывать его не нужно.

Коды провала генерации (errorCode, не HTTP)

Асинхронный отказ приезжает не в HTTP-ответе, а в поле errorCode объекта генерации при status: "FAILED":

  • content_policy — формулировка запроса нарушает политику модели (NSFW, насилие и т.п.); перепишите промпт.
  • moderation_rejected — сам материал отклонён проверкой безопасности модели. Повтор с тем же изображением и текстом даст тот же результат: измените материал или выберите другую модель.
  • prompt_rejected — модель отклонила конкретное содержимое запроса по своему правилу (например, имя исполнителя в тегах музыкальной модели). В отличие от content_policy, провайдер сам назвал, что убрать: повтор без изменений даст тот же ответ, измените текст запроса.
  • prompt_too_long — промпт длиннее, чем принимает эта модель.
  • reference_fetch_failed — не удалось скачать референс по вашей внешней ссылке; загрузите изображение через Студию или POST /v1/files.
  • input_fetch_failed — не удалось скачать файл, загруженный вами через Студию или POST /v1/files; загрузите его заново или выберите другой.
  • invalid_input — параметр в недопустимом диапазоне для этой модели.
  • insufficient_credit — приём генераций на этой модели временно остановлен на нашей стороне; списание за эту попытку отменено, выберите другую модель или попробуйте позже.
  • rate_limited, timeout, provider_unavailable, provider_internal — временные сбои на стороне провайдера.

Ретраи и автоматический refund

Если задача провалилась с финальной ошибкой провайдера (3 попытки worker исчерпаны), деньги автоматически возвращаются на баланс. Внутри системы возврат отражается в BalanceLedger с типом GENERATION_REFUND, а в GET /v1/billing/transactions — строкой с type: RELEASE. Идемпотентность гарантирует, что одна задача = одно списание + одно возможное возмещение.

Что делать с ошибкой

  1. Логируйте requestId и code.
  2. Для RATE_LIMIT_ERROR, SERVICE_UNAVAILABLE и GATEWAY_* — повторите запрос с экспоненциальной задержкой.
  3. Для VALIDATION_ERROR — исправьте параметры по error.details.fields[]. Для MODEL_UNAVAILABLE и MODEL_NOT_AVAILABLE — выберите другую модель, повтор не поможет.
  4. Для INSUFFICIENT_BALANCE — пополните баланс.
  5. Если непонятно — напишите в саппорт с requestId.
Errors · IskraGen Docs — IskraGen