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. Идемпотентность гарантирует, что одна задача = одно списание + одно возможное возмещение.
Что делать с ошибкой
- Логируйте
requestIdиcode. - Для
RATE_LIMIT_ERROR,SERVICE_UNAVAILABLEиGATEWAY_*— повторите запрос с экспоненциальной задержкой. - Для
VALIDATION_ERROR— исправьте параметры поerror.details.fields[]. ДляMODEL_UNAVAILABLEиMODEL_NOT_AVAILABLE— выберите другую модель, повтор не поможет. - Для
INSUFFICIENT_BALANCE— пополните баланс. - Если непонятно — напишите в саппорт с
requestId.