Устранение ошибок выставления счетов и ограничений расходов клиентов

Используйте вход через ShareAI для идентификации и явное разрешение «Оплатить через ShareAI» для действий, финансируемых аккаунтом. openid Одна область действия никогда не дает разрешения на расходы. Выводы ИИ требуют inference или утвержденного, согласованного surcharge гранта; payments запросы с отдельно подтвержденными покупками. Клиент управляет месячным лимитом ИИ в Консоли. Ваше приложение не может его изменить.

Обработка ошибок по коду#

HTTP 402 · insufficient_credits: платежный аккаунт не имеет достаточного количества неистекших кредитов, подходящих для данного провайдера/модели и запроса. Попросите клиента управлять своими кредитами. Некоторые кредиты имеют ограничения по провайдеру или модели.

HTTP 402 · application_spending_limit_exceeded: месячный лимит достигнут, зарезервированные запросы используют доступное разрешение, или плата за этот запрос превысила бы лимит. Не рассматривайте это как ограничение скорости или автоматически повторяйте запрос. Попросите клиента изменить лимит или подождать до reset_at.

HTTP 429 · oauth_rate_limit: временное ограничение запросов/одновременности. Следуйте Retry-After и ограниченному откату. HTTP 401 · consent_required: согласие истекло, отозвано или больше не действительно; получите новое разрешение вместо запроса на пополнение.

{
  "error": {
    "type": "billing_error",
    "code": "application_spending_limit_exceeded",
    "message": "This application's monthly AI spending limit has been reached or this request would exceed it. Manage the limit or wait for the next month.",
    "management_url": "https://console.shareai.now/?shareai_billing_context=OPAQUE_SHORT_LIVED_VALUE",
    "help": "https://console.shareai.now/?shareai_billing_context=OPAQUE_SHORT_LIVED_VALUE",
    "monthly_limit": "50",
    "reset_at": "2026-10-01T00:00:00Z"
  }
}

Две финансовые ошибки используют error.type = billing_error. management_url является местом восстановления клиента; help является его совместимым псевдонимом. monthly_limit является точной строкой десятичного числа в EUR и reset_at является UTC. Они присутствуют при ошибках лимита и могут отсутствовать при ошибках недостаточного кредита.

Открытие правильного платежного аккаунта#

Предложите видимую Управление платежами действие с использованием возвращенной URL-адреса. Непрозрачный контекст истекает через 15 минут, идентифицирует оригинальный платежный аккаунт и соединение, и сохраняется при перенаправлении входа. Консоль проверяет права владельца/администратора вошедшего посетителя перед выбором этого аккаунта. Не заменяйте это платежной страницей владельца приложения, не придумывайте идентификатор актера, не добавляйте токен доступа и не перенаправляйте клиента автоматически.

Используйте список разрешений для источника Консоли и rel="noopener noreferrer" если открываете новую вкладку. Ссылка является навигацией, а не авторизацией или доказательством того, что средства были добавлены. Не сохраняйте ее как постоянную закладку или в публичных журналах. После истечения срока действия клиент может открыть Платежи напрямую. Новый запрос может вернуть новую ссылку после явного запроса клиента на повторение.

const response = await fetch("https://api.shareai.now/api/v1/chat/completions", options);
const body = await response.json();
const error = body.error;
if (response.status === 402 && error?.type === "billing_error") {
  const message = error.code === "application_spending_limit_exceeded"
    ? "Your monthly limit for this app has been reached."
    : "Your ShareAI account needs eligible credits.";
  showBillingMessage(message);
  if (error.management_url) {
    const target = new URL(error.management_url);
    if (target.origin === "https://console.shareai.now") {
      // Render a user-activated link; never silently open it or retry spending.
      showManageBillingLink(target.href);
    }
  }
  return;
}
if (!response.ok || error) throw new Error(error?.message || "Request failed");
renderAnswer(body);

Потоковая передача и окончательный расчет#

ShareAI проверяет лимит перед допуском/привязкой и проверяет фактическую стоимость сети плюс надбавку атомарно при расчете. Одновременные запросы используют один и тот же лимит. Оценки ввода резервируют запас; длина вывода заранее неизвестна. Окончательная плата, которая превысила бы оставшееся разрешение, отклоняется без дебета за использование или кредита за надбавку разработчика.

Для SSE завершений чата обработайте event: error с теми же error.code и полями восстановления. Для SSE ответов обработайте response.failed и прочитайте response.error. Как только поток начинается, его HTTP-статус уже 200; частичное содержание не означает успешного завершения. Не отмечайте результат как завершенный, не выполняйте оплаченные действия вниз по потоку или автоматически повторяйте после терминальной ошибки. Не потоковые Чат, Ответы, Встраивания и Изображения показывают ошибку платежа как корневой HTTP 402 error конверт.

Область действия и сбросы#

Календарный месяц отсчитывается по UTC. Лимит устанавливается на каждый платящий аккаунт и приложение, общий для OAuth-клиентов, грантов и обновленных токенов; сервис клиента использует свой стабильный рабочий идентификатор даже при ротации Production-ключей. Учитываются только фактические расходы на AI-сеть плюс наценка. Фиксированные подписки и отдельно подтвержденные покупки имеют собственную авторизацию на оплату и не расходуют этот лимит AI. Нулевое значение приостанавливает дополнительные расходы на AI; null означает отсутствие лимита. Прошлые начисления сохраняются при редактировании лимита или повторной авторизации подключения.

Это инструменты управления для клиентов в Console, а не конечная точка для разработчиков для увеличения бюджета. Продолжайте соблюдать области действия гранта, утвержденные модели, предпочтения провайдера клиента и согласованные условия наценки. Руководство по выставлению счетов для клиентов · API оформления заказа.