Ошибки
Каждая ошибка — JSON-объект с полями code (стабильный код для программы), error (короткое
сообщение для человека), requestId и retryable (может ли повтор того же запроса позже пройти),
а также category и severity. Идентификатор запроса возвращается и в заголовке X-Request-Id.
Ответы никогда не содержат стек, исходную ошибку провайдера или внутренние цены.
Поле acceptance: "rejected", если оно есть, подтверждает отказ команды до её принятия.
Без этого подтверждения потеря ответа, сетевой сбой или HTTP-ошибка сами по себе не доказывают,
что задача не создана. Сохраните исходные тело, quoteId и Idempotency-Key; проверяйте прежнюю
операцию либо повторяйте ту же команду. retryable не разрешает новую покупку с другим ключом.
Непредвиденный сбой — 500 с кодом DEVELOPER_API_ERROR (у /api/v1/tts — DEVELOPER_TTS_ERROR);
сбой создания уже принятой операции — 500 с кодом PODCAST_CREATE_FAILED или NEWS_CREATE_FAILED.
У принятого Podcast или News причины отказа следующих платных действий приходят в статусе задачи,
а не как HTTP-ответ исходного запроса создания. Нехватка
баланса создаёт состояние paused_insufficient_credits и не является ошибкой.
Ожидание средств провайдера перед новым модельным вызовом передаётся необязательным
recovery.reasonCode: PROVIDER_FUNDING_READ_UNAVAILABLE — временно недоступна проверка,
PROVIDER_FUNDING_INSUFFICIENT — проверка подтвердила нехватку средств провайдера. Это не отказ
генерации и не нехватка кредитов владельца: сохраняйте исходную операцию и проверяйте её статус.
Неверные учётные данные или конфигурация не считаются таким автоматическим ожиданием.
Для завершившегося с ошибкой News поле task.errorCode содержит только стабильный код продукта.
Оно не раскрывает цитаты, закрытый контекст исследования или текст ошибки провайдера. При
NEWS_EVIDENCE_INSUFFICIENT проверьте доступность и принадлежность сохранённых материалов;
при содержательном недостатке уточните тему или доступные материалы. При сбое сервиса сначала
проверьте статус и чек. Допустимое сохранённое
задание можно продолжить из мини-приложения; неизвестный внешний результат не допускает повтор без доказательства.
Повтор создания уже принятого задания с тем же ключом идемпотентности возвращает прежнее задание.
| Код | HTTP | Когда |
|---|---|---|
API_KEY_REQUIRED |
401 | нет заголовка Authorization: Bearer |
INVALID_API_KEY_FORMAT |
401 | заголовок Authorization не в виде Bearer <ключ> |
INVALID_API_KEY |
401 | ключ не найден |
API_KEY_REVOKED, API_KEY_EXPIRED |
401 | ключ отозван или истёк |
API_KEY_SCOPE_DENIED |
403 | у ключа нет нужного разрешения |
API_KEY_RATE_LIMITED |
429 | превышен лимит запросов в минуту |
API_KEY_QUOTA_EXCEEDED |
402 или errorCode задачи |
не хватает квоты ключа |
INSUFFICIENT_CREDITS |
402 | не хватает кредитов на балансе владельца |
OPERATION_SPENDING_LIMIT |
errorCode задачи |
следующий вызов не помещается в предел расходов выпуска |
API_KEY_QUOTE_MISMATCH |
409 | котировка выдана другому ключу |
QUOTE_FINGERPRINT_MISMATCH |
409 | тело создания отличается от тела котировки |
QUOTE_EXPIRED, QUOTE_ALREADY_CONSUMED |
409 | котировка истекла или уже использована |
QUOTE_NOT_FOUND |
404 | котировки нет |
INVALID_QUOTE |
400 | в теле создания или Continue нет допустимого quoteId |
IDEMPOTENCY_KEY_REQUIRED |
400 | нет заголовка Idempotency-Key |
INVALID_IDEMPOTENCY_KEY |
400 | Idempotency-Key — не 8–128 символов A-Za-z0-9._:- |
IDEMPOTENCY_CONFLICT |
409 | ключ идемпотентности уже использован с другим телом |
UNSUPPORTED_API_FIELD |
400 | в теле есть поле вне публичного контракта |
INVALID_MODE, INVALID_TEXT, INVALID_LENGTH_PRESET, INVALID_GROUNDING, INVALID_RESEARCH_URL и другие INVALID_* |
400 | некорректное значение поля |
INVALID_BUDGET |
400 | maximumCredits не является положительным безопасным целым числом или null |
INVALID_NEWS_TOPIC |
400 | тема не из каталога и не ваша |
INVALID_NEWS_INPUT |
400 | некорректные период, голос, язык или предпочтения новостей |
NEWS_EVIDENCE_INSUFFICIENT |
errorCode задачи |
сохранённые материалы отсутствуют или их идентичность не соответствует принятому заказу; озвучка не запускается |
NEWS_RESEARCH_UNCONFIRMED |
errorCode задачи |
найденные материалы не удалось подтвердить для выбранной темы и периода; выберите другую тему или период |
NEWS_RESEARCH_INCOMPLETE |
errorCode задачи |
исследование не завершено, выпуск пока не создан; проверьте статус и чек перед допустимым продолжением |
NEWS_NARRATION_EMPTY |
errorCode задачи |
нет пригодного принятого текста для озвучки |
NEWS_SERVICE_UNAVAILABLE, NEWS_PROVIDER_UNAVAILABLE |
errorCode задачи |
текущий исполнитель или внешний сервис не может завершить работу |
NEWS_GENERATION_FAILED, VOICE_SYNTHESIS_FAILED |
errorCode задачи |
выпуск или готовое аудио не удалось создать |
PODCAST_NOT_FOUND, TASK_NOT_FOUND |
404 | операции нет или она создана другим ключом |
PODCAST_CONTINUATION_UNAVAILABLE |
409 | failed-задачу нельзя безопасно продолжить или подтверждение не соответствует исходной работе |
PODCAST_CONTINUATION_QUOTE_MISMATCH |
409 | котировка продолжения относится к другой редакции задачи |
NEWS_NOT_READY |
409 | результат или аудио ещё не готовы |
PODCAST_NOT_CANCELLABLE, NEWS_NOT_CANCELLABLE |
409 | операция уже завершена |
CATALOG_NOT_FOUND, SERVICE_UNAVAILABLE |
503 | генерация временно недоступна на этом развёртывании |
PRICING_AUTHORITY_UNAVAILABLE |
503 | нет пригодной опубликованной пары ценовой политики и каталога для новой котировки |
RESEARCH_EXTRACTION_UNAVAILABLE |
503 | для Quick/Deep нет маршрута извлечения и пригодного текста библиотеки; котировка отказывает до платной работы |
RANGE_NOT_SATISFIABLE |
416 | некорректный диапазон аудио |
INVALID_JSON, INVALID_REQUEST_BODY |
400 | тело не разобрано |
UNSUPPORTED_BODY_ENCODING |
415 | неподдерживаемая кодировка тела |
PAYLOAD_TOO_LARGE |
413 | тело больше 10 МиБ |
NOT_FOUND |
404 | неизвестный путь под /api/v1/ |