Расчёты
Ошибки и безопасные повторы
Как не создать второй платный запрос после сетевой ошибки.
Обычная HTTP-ошибка содержит error.code, error.message и error.request_id. Идентификатор всегда выглядит как req_ и 32 символа, совпадает с заголовком X-Request-Id ответа, а принятый запрос потом можно найти с ним же в истории использования. Сообщение не раскрывает внутренние маршруты, внутренний ID поставщика или секреты. В MCP результат ошибки инструмента помечен isError=true.
| Ситуация | Действие |
|---|---|
| validation_error / unsupported_parameter | Исправьте форму до новой отправки |
| unauthorized / insufficient_scope | Проверьте ключ и необходимые права |
| rate_limited (HTTP 429) | Превышен лимит запросов в минуту. Выдержите Retry-After и повторите тот же запрос; числа и заголовки — в лимитах |
| api_key_daily_budget_exceeded (HTTP 429) | Проверьте дневной бюджет и резервы |
| insufficient_balance | Проверьте доступный баланс |
| quote_exceeds_limit | Получите новую цену и явно задайте допустимый предел |
| unsupported_media_type (HTTP 415) | Отправьте тело в формате JSON с заголовком Content-Type: application/json; multipart не поддерживается |
| payload_too_large (HTTP 413) | Тело запроса больше 10 МиБ. Уменьшите данные; файлы передавайте через загрузку |
| method_not_allowed (HTTP 405) | Путь существует, но не для этого метода. Допустимые методы перечислены в заголовке Allow |
| invalid_preflight (HTTP 400) | Предварительный запрос браузера (CORS, метод OPTIONS) без Origin или Access-Control-Request-Method. Браузер добавляет их сам; серверным клиентам OPTIONS не нужен |
| stream_not_enabled (HTTP 503) | Потоковый режим временно выключен. Запрос не принят, деньги не резервировались: отправьте его без stream или повторите позже |
| idempotency_conflict | Не меняйте тело уже принятого запроса; используйте исходные данные |
| model_not_found (HTTP 404) | Такой модели нет в каталоге: проверьте ID в каталоге. Запрос отклонён до резерва, деньги не списывались; повторять без исправления ID не нужно |
| model_unavailable | Проверьте доступность операции; запрос мог быть отклонён до отправки |
| cancellation_not_safe | Отмена после отправки запрещена; дождитесь сверки |
| provider_outcome_refunded | Модель не вернула результат; резерв возвращён на баланс, запрос можно отправить заново с новым Idempotency-Key |
| result_not_delivered | Результат не удалось доставить по вине платформы за срок восстановления; резерв возвращён на баланс, платить не нужно, запрос можно отправить заново с новым Idempotency-Key |
| service_unavailable (HTTP 503) | Временная перегрузка. Выдержите Retry-After. Если вы отправляли Idempotency-Key, повторите тот же запрос с тем же ключом и телом. Без своего ключа сначала проверьте историю использования: повтор станет новым запросом |
| invalid_input_file (HTTP 400) | Файл не подходит для запроса: проверьте тип и размер. Для изображений в чате — PNG, JPEG или WebP до 10 МиБ. Запрос отклонён до резерва |
| storage_not_configured (HTTP 503) | Хранилище файлов недоступно, запрос с файлами не принят и деньги не резервировались. Повторите позже |
| file_not_ready / file_scanning | Дождитесь проверки файла |
| file_expired | Срок хранения истёк |
При разрыве соединения результат не известен. Повторяйте тот же endpoint с прежним ключом credential, Idempotency-Key и телом. Сохранённый результат возвращается без второй отправки и списания. Не включайте слепой SDK retry со случайным новым Idempotency-Key. В текстовых endpoint заголовок можно не передавать, но тогда сервер подставит случайный ключ и повтор после сетевой ошибки будет оплачен как новый запрос; поэтому передавайте его всегда. Для изображений, видео, аудио и других медиа-операций заголовок обязателен.
HTTP 202 для медиа означает принятое задание. Для текстового пути он может означать незавершённую обработку; billing и сохранённый запрос остаются источником состояния. Проверьте историю и не выдавайте этот ответ за окончательный текст модели.