Ошибки и лимиты

Отказ приходит в одной и той же форме на всех ручках, а по заголовкам ответа видно, сколько запросов осталось и когда повторять. Эта статья описывает то и другое.

Форма отказа#

{
  "error": {
    "code": "cost_above_limit",
    "message": "The generation costs more than the maxCredits ceiling in the request.",
    "retryable": false,
    "details": { "credits": 62, "maxCredits": 40 }
  }
}

code — машинный идентификатор, единственное, на что стоит программировать. message написан для человека, читающего лог, и может меняться. retryable отвечает, имеет ли смысл повторить тот же запрос без изменений. details есть не всегда: там лежит машинная диагностика — перечень проблем валидации, незакрытые входы, числа.

Локализации нет: ответ читает программа, а не человек в интерфейсе.

Каждый ответ несёт X-Request-Id. Он же записан в наших логах, поэтому разбор происшествия начинается с одной строки — приложите его к обращению в поддержку.

Коды и статусы#

Список закрыт: код, которого нет в таблице, наружу не уходит. Новые значения могут появляться — незнакомый код обрабатывайте по числовому статусу и признаку retryable из ответа.

Повторять или нет, говорит retryable в самом ответе: у части кодов это зависит от причины, а не от кода. У всех отказов по частоте и временной недоступности есть заголовок Retry-After.

Отказ самой генерации#

Провалившаяся генерация — это ответ 200 с состоянием failed, а не отказ запроса: запрос выполнен, не удалась работа модели. Причина лежит внутри генерации и устроена иначе, чем отказ ручки:

{
  "generationId": "8f14e45f-ceea-467a-9a3e-4b1c2d5e7f80",
  "state": "failed",
  "error": {
    "code": "prompt_validation",
    "reason": "prompt_too_long",
    "message": "The prompt is longer than this model accepts.",
    "retryable": false,
    "hint": "The model could not work with this prompt. Rewrite it, or pick another family.",
    "details": { "limit": 8000 }
  }
}

code — класс отказа, список закрыт. hint называет действие, а не диагноз: что менять перед следующей попыткой. details появляется там, где из отказа удалось достать числа — например предел длины промпта у конкретной модели.

reason — причина внутри класса, и программировать разное поведение стоит по ней. Один класс покрывает несколько разных отказов: prompt_too_long, prompt_failed и prompt_images_failed — всё это prompt_validation, но первый чинится обрезкой промпта, а последний — заменой входных изображений. Список причин, в отличие от списка классов, открыт и пополняется. Опубликованную причину мы не переименовываем, а незнакомую обрабатывайте по code.

Дословную формулировку модели мы наружу не отдаём — в message приходит наш текст по причине отказа. Чтобы подняли оригинал, назовите generationId в обращении в поддержку.

Причина unclassified при классе internal_error означает, что отказ не удалось отнести ни к одной известной причине. Обрабатывайте его по code; со временем такие отказы получают точную причину.

Частота и одновременность#

Ограничений два, и считаются они на пользователя, а не на ключ: сорвавшийся скрипт одного участника команды не должен закрывать API остальным.

Частота. Сейчас это 600 запросов в минуту. Превышение — 429 rate_limited с заголовком Retry-After.

Одновременность. До 32 запросов в работе одновременно. Потолок рассчитан на ожидание через wait, где запрос висит до минуты; больше тридцати двух открытых ожиданий — повод перейти на историю или на вебхуки. Превышение — 429 too_many_concurrent.

Точные числа приходят в заголовках каждого ответа, и опираться стоит на них, а не на значения в тексте:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 587
X-RateLimit-Reset: 1785974160

X-RateLimit-Reset — момент обнуления счётчика в секундах Unix.

Отдельно от этого действуют потолки траты самого ключа — суточный и разовый. Они описаны в статье Ключ и права.

Потолки размеров#

Две последние границы — заслон транспорта, а не пределы моделей: те заметно строже. Сколько входов принимает вариант, видно в подробностях семейства (inputs.images.max и соседние поля), а предел длины промпта — в описании параметра, если модель его объявляет. Лишний файл отвергается подбором варианта с кодом variant_not_resolved, слишком длинный промпт — самой моделью с классом prompt_validation, и там же в details приходит настоящее число.

Машинное описание#

GET /api/v1/openapi.json отдаёт спеку OpenAPI: пути, схемы запросов и ответов, коды отказа. Она собирается из тех же схем, которыми проверяется вход, поэтому разойтись с поведением не может.

Спека закрыта тем же ключом, что и остальные ручки, и требует права catalog:read: документ описывает ручки, но не даёт ими пользоваться.