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

Эта страница — то, что открывают в три часа ночи. Здесь перечислены все ошибки, которые может вернуть публичный Prostor API, что каждая из них значит и что с ней делать.

Конверт ошибки

Любая ошибка — и наша, и проброшенная от провайдера — приходит в одном и том же JSON-конверте:

{
  "error": {
    "message": "unknown model: gpt-4o-minii — call GET /v1/models for the models this key can use",
    "code": 404,
    "type": "not_found",
    "metadata": {
      "prostor_code": "model_not_found"
    }
  }
}

Три поля, на которые можно ветвиться, и они означают разные вещи:

Ветвление на практике:

const res = await fetch(`${BASE}/chat/completions`, { /* ... */ });
if (!res.ok) {
  const { error } = await res.json();
  const code = error?.metadata?.prostor_code;
  const type = error?.type;

  if (code === "insufficient_credits") throw new NeedsTopUp(error.message);
  if (code === "model_not_found") throw new BadModelId(error.message);   // опечатка, не ретраить
  if (type === "rate_limit_exceeded") {
    const wait = Number(res.headers.get("Retry-After") || 1);
    return retryAfter(wait * 1000);
  }
  if (type === "provider_unavailable" || error.code >= 500) return retryWithBackoff();
  throw new Error(error?.message || "Prostor API error");
}

Ошибки, пришедшие от routing core и провайдеров, проксируются с их HTTP-статусом, но приводятся к этому же конверту: code нормализуется в числовой статус, а внутренние поля (маршрутизация, идентификаторы провайдера, retry_after_ms, версия ядра) вырезаются. Если тело ошибки провайдера не разбирается как JSON, вы получите prostor_code: "provider_error" с текстом the upstream provider returned an error.

Канонические типы

error.type принимает ровно эти значения:

Полный список кодов

Все prostor_code, которые может вернуть публичный API.

400 — некорректный запрос

401 / 403 — ключ и права

Ни одна из этих ошибок не лечится повтором. Ретрай только умножает нагрузку.

402 — кредиты

Отдельный раздел ниже: Про 402 insufficient_credits. Это ошибка, которая чаще всего прилетает неожиданно.

404 — нет такого

405 / 408 / 409

429 — лимиты и перегрузка

Все 429 несут Retry-After (см. раздел про лимиты). Все они ретраибельны.

5xx — не ваша вина

Ошибка провайдера отдаётся с его собственным HTTP-статусом (400, 429, 500, 502…). Резерв кредитов при этом возвращается целиком — за неудавшуюся генерацию вы не платите.

Что ретраить, а что нет

Backoff: экспоненциальный с джиттером, старт 1 s, не больше 5 попыток. Для 429 — не быстрее, чем разрешает Retry-After.

Про 402 insufficient_credits

Самая контринтуитивная ошибка API. Она может прилететь при живом, положительном балансе.

Почему

Перед тем как отправить запрос в модель, gateway ставит на кошелёк предавторизационный резерв (hold) — сумму, которой заведомо хватит на худший исход этого запроса. Резерв считается так:

• prompt-часть — оценка по размеру тела запроса в байтах (оценка намеренно завышенная: кириллица занимает больше байт, чем латиница, и её токенов больше, чем даёт наивный расчёт);
• completion-часть — ровно ваш max_tokens. А если вы его не передали — 8192 токенов (значение по умолчанию, см. раздел про клэмп);
• обе части умножаются на розничную цену модели и округляются в большую сторону.

То есть запрос без max_tokens резервирует столько, сколько стоили бы 8192 выходных токена этой модели — даже если модель ответит одним словом. На дорогой модели это ощутимая сумма. Резервы одновременных запросов складываются: при лимите в 32 параллельных запроса на ключ в воздухе может висеть 32 таких резерва.

Итог: клиент, чей реальный расход составил бы, скажем, 200 кредитов, получает insufficient_credits с текстом insufficient credits to cover max_tokens for this request задолго до того, как баланс действительно кончился.

Что делать

curl -s "$PROSTOR_API_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $PROSTOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model-id-from-/v1/models>",
    "messages": [{"role": "user", "content": "Привет"}],
    "max_tokens": 256
  }' | jq .

Дальше по чек-листу:

1. Передать max_tokens (или max_completion_tokens, или max_output_tokens для /responses) — реалистичный, а не «на всякий случай побольше».
2. Снизить параллелизм: меньше одновременных запросов — меньше одновременных резервов.
3. Проверить баланс: GET /v1/credits → prostor.balance_credits.
4. Проверить, не упёрлись ли в лимит ключа, а не в кошелёк: GET /v1/key → prostor.limits.credits_total. Если исчерпан он, ошибка будет другая — 429 credit_limit_exceeded.

Неизрасходованный резерв возвращается

Резерв — не списание. После того как ответ получен, gateway списывает фактическую стоимость по реальному usage, а остаток резерва немедленно возвращается на баланс. Если запрос упал (ошибка провайдера, ошибка ядра) — возвращается весь резерв. Брошенные резервы (например, процесс упал в момент расчёта) подчищаются автоматической сверкой.

Что именно списано, всегда видно в трёх местах: usage.cost (в USD), usage.cost_details.billed_credits (в кредитах) и заголовок X-Prostor-Cost-Credits.

Лимиты и конкурентность

Заголовки

Все шесть заголовков объявлены в Access-Control-Expose-Headers, поэтому их видно и из браузера.

Что именно ограничено

Актуальные значения именно вашего ключа — в GET /v1/key → prostor.limits, prostor.concurrency_limit, prostor.max_output_tokens.

В GET /v1/key поля limits.requests_per_minute и limits.tokens_per_minute всегда показывают used: 0 и remaining: null — счётчики минутного окна наружу не публикуются. Не стройте на них логику; ориентируйтесь на Retry-After в фактическом 429.

Ошибки в стриминге

Если ответ уже начал отдаваться (200 OK + text/event-stream), поменять HTTP-статус нельзя. Поэтому ошибки, случившиеся после старта стрима, приходят внутри самого стрима, отдельным SSE-событием.

Для /chat/completions:

data: {"error":{"message":"upstream generation failed","type":"stream_error"}}
data: [DONE]

Для /responses — типизированное событие ошибки Responses API с полем code.

Отдельный случай — переполнение буфера: если ответ модели превысил безопасный лимит для стриминга, попытка отбрасывается целиком и клиент получает

data: {"error":{"message":"upstream response exceeded the safe streaming limit","type":"stream_error"}}
data: [DONE]

Обрыв соединения НЕ отменяет генерацию

Это важно и стоит денег.

Если вы разрываете соединение посреди стрима (таймаут HTTP-клиента, AbortController, закрытая вкладка), gateway не отменяет запрос у провайдера. Генерация дочитывается до конца, её реальный usage фиксируется, и она списывается с вашего баланса полностью. То же верно и для нестриминговых запросов.

Так сделано осознанно: только полный ответ провайдера даёт достоверный usage, а списывать «по оценке» — значит систематически ошибаться в чью-то сторону. Отменяемых генераций у API сейчас нет.

Последствия для клиента:

• ставьте HTTP-таймаут больше ожидаемого времени генерации, иначе вы будете платить за ответы, которых не увидели;
• в GET /v1/generation?id= у такой генерации будет interrupted: true и finish_reason: "client_disconnected", а cost_credits — полная стоимость;
• retry по своему таймауту без идемпотентности = двойное списание. См. раздел про Idempotency-Key.

Предельное время жизни стрима на стороне gateway — 20 минут; нестримингового запроса к ядру — 120 секунд.

Что в usage у стрима

В финальном usage-чанке стрима поля is_estimated и interrupted всегда false — на момент отправки чанка их значения ещё не известны. Достоверные значения (в том числе interrupted: true после обрыва) появляются только в GET /v1/generation?id=<X-Generation-Id>.

Если провайдер не прислал терминальный usage-чанк, токены оцениваются, причём оценка намеренно консервативна: completion считается не меньше, чем весь зарезервированный max_tokens. Такая генерация помечается is_estimated: true в GET /v1/generation. Ещё одна причина не оставлять max_tokens пустым.

Тихий клэмп max_tokens

Правила:

• явный max_tokens резервируется и форвардится как запрошено — реальный предел модели дальше применяет провайдер;
• жёсткий потолок шлюза — 64000 (у ключа может быть свой max_output_tokens, тогда он жёсткий именно для этого ключа); значение выше снижается до него;
• дефолт 8192 — не потолок, а лишь то, что подставляется, если ни max_tokens, ни max_completion_tokens (chat), ни max_output_tokens (/responses) не переданы.

Где посмотреть своё число, а не гадать:

• GET /v1/models → у каждой текстовой модели top_provider.max_completion_tokens;
• GET /v1/key → prostor.max_output_tokens.

curl -s "$PROSTOR_API_BASE_URL/key" \
  -H "Authorization: Bearer $PROSTOR_API_KEY" | jq '.prostor.max_output_tokens'

Если вам нужен ответ длиннее потолка — разбивайте задачу на несколько запросов; поднять потолок для ключа может администратор.

Idempotency-Key: как сделать ретраи безопасными

Ретрай по таймауту без идемпотентности — это второй счёт за ту же работу. Особенно больно с медиа: изображение и видео тарифицируются фиксированной ценой за генерацию, поэтому повторно отправленный запрос на картинку — это ровно вторая картинка и ровно второе списание.

Передайте заголовок:

curl -s "$PROSTOR_API_BASE_URL/images/generations" \
  -H "Authorization: Bearer $PROSTOR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0f2b9a5e-4a1c-4c2b-9f0d-7c1e5b3a8d61" \
  -d '{
    "model": "<image-model-id-from-/v1/models>",
    "prompt": "a cat riding a bike, watercolor",
    "n": 1
  }' | jq .

Как это работает:

• первый запрос выполняется как обычно; при успешном (2xx) ответе тело и статус сохраняются;
• повтор с тем же ключом возвращает сохранённый ответ дословно, с заголовком Idempotent-Replayed: true. Повторного списания нет;
• повтор, пока первый запрос ещё выполняется, вернёт 409 idempotency_conflict — подождите и повторите;
• если первый запрос завершился ошибкой, ключ освобождается: ретрай с тем же ключом выполнится по-настоящему (это то, что вам и нужно);
• записи живут 24 часа, потом удаляются.

Ключ привязан к пути и телу

Сохранённая запись — это ваш Idempotency-Key плюс отпечаток пути и байтов тела. Тот же Idempotency-Key с другим телом или на другом эндпоинте — другая заявка: она выполнится и спишется. Это защищает настоящие ретраи (тот же запрос) и не даёт переиспользовать ключ для другого запроса. Генерируйте UUID на каждую логическую операцию и переиспользуйте его только при ретрае байт-в-байт того же запроса.

Где идемпотентность НЕ работает

Работает на: POST /v1/chat/completions и POST /v1/responses (только без стриминга), POST /v1/images/generations, POST /v1/videos/generations, POST /v1/videos/submit, POST /v1/embeddings.

Что приложить к обращению в поддержку

• X-Request-Id (он же X-Generation-Id) из заголовков ответа — это единственный идентификатор, по которому мы найдём запрос;
• полное тело ошибки (error.code, error.type, error.metadata.prostor_code);
• время запроса с точностью до минуты и модель.

Свою сторону истории можно посмотреть самому:

curl -s "$PROSTOR_API_BASE_URL/generation?id=<X-Generation-Id>" \
  -H "Authorization: Bearer $PROSTOR_API_KEY" | jq .

Ответ покажет status, токены, cost_credits, finish_reason, latency, а также флаги interrupted и is_estimated.