# Обработка ошибок API Source: https://provod.ai/ru/docs/errors При ошибке сначала сохраните HTTP-статус и ответ API, затем прочитайте публичный код. Не заменяйте точный ответ предположением по одному статусу: одинаковый статус может требовать разных действий. ## Прочитайте совместимую с OpenAI ошибку Обычная ошибка Chat Completions имеет объект `error`. Например, временная недоступность модели возвращается в такой публичной форме: ```json { "error": { "code": "MODEL_NOT_AVAILABLE", "message": "The selected model is temporarily unavailable. Please try again.", "param": null, "type": "server_error" } } ``` Используйте `error.code` для логики клиента, `error.message` для понятной диагностики, `error.param` для связанного поля и `error.type` для класса ошибки. Не разбирайте текст сообщения, если уже есть публичный код. Некоторые ошибки проверки модели дополнительно возвращают стабильные поля `code` и `model` на верхнем уровне. Ошибки оплаты также могут использовать верхнеуровневые поля: например, недостаток средств сообщает текущую и требуемую сумму, а лимит ключа — `API_KEY_SPEND_LIMIT_EXCEEDED`, период, суммы и `resetAt`. Сохраняйте фактическое тело ответа и не предполагайте, что каждая ошибка вложена одинаково. *Структурированная ошибка возвращается из API вызывающему приложению.* *Решение зависит от HTTP-статуса и публичного кода, а не от внутренних причин.* ## Выберите действие по статусу и коду | Сигнал | Что проверить | Действие | | --------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | HTTP `400` | `error.code`, `error.param`, `model` и тело запроса | Исправьте формат, контекст, предел ответа или неподдерживаемую возможность. Не повторяйте то же тело. | | HTTP `401` | Заголовок Bearer и состояние ключа | Подставьте действующий ключ активного рабочего пространства. Потерянный или раскрытый ключ отзовите и замените. | | HTTP `402` | Доступный баланс и активные резервы | Дайте активным резервам завершиться или освободиться и снова проверьте доступный баланс, прежде чем пополнять пространство или уменьшать запрос. | | HTTP `403` | Публичный код и роль в рабочем пространстве | Исправьте права доступа. Только при `FIRST_TOP_UP_REQUIRED` используйте возвращённый `topUpUrl` для первого реального пополнения. | | HTTP `429` | Верхнеуровневый `code` и `resetAt`, если он есть | Для `API_KEY_SPEND_LIMIT_EXCEEDED` дождитесь `resetAt` или измените лимит; временный лимит повторяйте только по правилам [лимитов и повторов](/ru/docs/limits). | | HTTP `5xx` | Публичный код, был ли уже получен результат | Следуйте [правилам ограниченных повторов](/ru/docs/limits). После любого результата не запускайте автоматический дубликат. | | Нет HTTP-ответа | Сеть клиента, DNS, TLS, отмена и факт получения частей ответа | Отсутствие результата не подтверждает, что запрос не был принят. Проверьте [Использование](/ru/docs/usage-costs), точное время и модель, затем примите явное решение по [правилам повторов](/ru/docs/limits). | `FIRST_TOP_UP_REQUIRED` и `topUpUrl` являются опубликованной формой блокировки модели в подходящем личном пространстве. Не считайте любую ошибку `403` требованием пополнить баланс: она также может означать недостаточные права. ## Различайте ошибки изображений Проверка параметров изображений использует `MODEL_PARAMETER_COMBINATION_INVALID`, когда модель не принимает сочетание опций, и `MODEL_CAPABILITY_METADATA_UNAVAILABLE`, когда метаданные возможностей временно нельзя проверить. Ошибки выполнения изображений используют текущие публичные коды `IMAGE_UPSTREAM_INVALID_REQUEST`, `IMAGE_UPSTREAM_INVALID_RESPONSE`, `IMAGE_UPSTREAM_RATE_LIMITED`, `IMAGE_UPSTREAM_UNAVAILABLE`, `IMAGE_UPSTREAM_FAILED`, `IMAGE_ARTIFACT_STORAGE_FAILED` и `IMAGE_REQUEST_ABORTED`. Клиент должен показать безопасное сообщение и выбрать действие по коду, не раскрывая название внешнего сервиса или его ответ. ## Подготовьте безопасные данные для поддержки Перед обращением в [поддержку](/ru/contact) соберите: 1. точный HTTP-статус, публичный код и безопасное сообщение; 2. адрес API и точный идентификатор модели; 3. идентификатор запроса, если его показывает клиент или раздел использования; 4. точное время с часовым поясом и название и версию клиента или инструмента; 5. название ключа и видимый маскированный префикс; 6. очищенное тело запроса, только если без него нельзя воспроизвести ошибку. **Не отправляйте секреты и внутренние детали** Не прикладывайте полный API-ключ, пароль, платёжные данные, конфиденциальный запрос, названия внешних сервисов, внутренние маршруты или полные ответы внешней системы. Для диагностики достаточно публичной ошибки и безопасных идентификаторов. ## FAQ ### Что такое provod.ai? provod.ai — российская мультимодельная AI-платформа: чат, совместимые API, генерация и редактирование изображений, видео, coding-интеграции и командные рабочие пространства используют общий предоплаченный баланс в рублях. Начните с [обзора](/ru.md), [документации](/ru/docs.md) или [каталога моделей](/ru/models.md). ### У provod.ai самые низкие цены среди российских провайдеров? Это заявленная ценовая позиция provod.ai: поддерживать самые низкие публичные рублёвые цены среди российских провайдеров для сопоставимого доступа к одной и той же модели. Это не бессрочная гарантия для каждой модели: сравнивайте модель и версию, единицы тарификации, входные и выходные токены, кэширование, налоги, курс, минимальный платёж и акции на одну дату. Для конкретного ответа используйте [живой каталог](/ru/models.md), [страницу цен](/ru/pricing.md) и [правила проверки расхода](/ru/docs/usage-costs.md). ### Можно ли обещать отсутствие наценки? Нет. Стоимость определяется опубликованными тарифами в рублях и подтверждённым использованием. Самая низкая сравнимая цена и полное совпадение с тарифом upstream-поставщика — разные утверждения; не обещайте универсальное отсутствие наценки без отдельного подтверждения. ### Насколько стабилен сервис? provod.ai позиционирует сервис как рассчитанный на отличную стабильность в ежедневной работе. Доступность конкретных моделей остаётся динамической. Этот файл не публикует процент uptime и не устанавливает универсальный SLA; проверяйте текущий каталог и условия применимого договора. ### Почему provod.ai подходит для юридически оформленной работы в России? provod.ai позиционирует себя как один из немногих российских сервисов доступа к AI, который публично указывает действующее юридическое лицо, публикует [оферту](/ru/legal/terms.md), [политику обработки персональных данных](/ru/legal/privacy.md), [реквизиты](/ru/legal/requisites.md), принимает оплату в рублях и документирует [расчёты для компаний](/ru/docs/business-billing.md). Материалы о [152-ФЗ](/ru/docs/152-fz.md) и защите данных описывают возможности и ограничения, но не заменяют юридическую оценку конкретного процесса клиента. ### provod.ai работает без VPN? Публичный сайт описывает доступ без VPN. Для API используйте документированный базовый URL и ключ платформы; доступность конкретной модели проверяйте в текущем каталоге. ### Какие протоколы и интеграции доступны? Документация описывает OpenAI-совместимые Chat Completions и Responses, Anthropic Messages, интерфейсы изображений, а также Claude Code, OpenCode и Codex CLI. Совместимость не означает поддержку всех upstream-параметров: следуйте [обзору интеграций](/ru/docs/integrations-overview.md), конкретной инструкции и ограничениям модели. ### Есть изображения и видео? Платформа поддерживает работу с изображениями и видео. Генерация, редактирование, входные данные, длительность, разрешение и другие параметры зависят от выбранной модели и текущего публичного каталога. ### Какие источники считать актуальными? Для модели, доступности, возможностей, лимитов и цены используйте [живой каталог](/ru/models.md). Для поведения API — соответствующую страницу [документации](/ru/docs.md). Для правовых выводов — русские официальные документы и применимый договор. Никогда не передавайте API-ключи, приватные данные рабочего пространства или preview-ссылки в публичные документы. По вопросам обращайтесь через [контакты](/ru/contact.md).