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) — ключ отсутствует, невалиден или отозван.
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 не сравнивается. Повтор с тем же ключом в пределах одного пользователя возвращает уже существующую генерацию (id, status, costRub), не создаёт новую и не списывает деньги второй раз, даже если тело отличается.

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

PROVIDER_ERROR (502) — общая ошибка провайдера модели.
UPSTREAM_CIRCUIT_OPEN (503) — приём генераций на модели временно остановлен на нашей стороне, деньги не списаны; повтор сразу не поможет — выберите другую модель или попробуйте позже.
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; это поле не отдаётся публичным API. Идемпотентность гарантирует, что одна задача = одно списание + одно возможное возмещение.

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

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