Лимиты расходов Claude apps gateway

Ограничьте расходы каждого разработчика через Claude apps gateway по дням, неделям или месяцам. Установите лимиты с помощью Admin API, и шлюз будет их соблюдать в реальном времени при каждом запросе.

Лимиты расходов ограничивают, сколько каждый разработчик может потратить через ваш Claude apps gateway в течение дня, недели или месяца. Когда разработчик превышает свой лимит, шлюз возвращает 429 при следующем запросе и блокирует его до сброса периода или пока администратор не повысит лимит. Используйте лимиты расходов, чтобы установить потолок расходов для каждого разработчика, группы или всей организации на общем учетном данном.

Claude apps gateway пересылает все вычисления через одно общее учетное данное вышестоящего провайдера, поэтому счет вашего провайдера относит все к этому учетному данному, а не к отдельным разработчикам. Без лимитов на разработчика один неконтролируемый флот агентов может потратить всю приверженность организации. Лимиты расходов — это представление шлюза на уровне разработчика и автоматический выключатель поверх этого общего счета.

Установка лимита

С настроенным блоком admin: в gateway.yaml, gateway предоставляет Admin API по адресу /v1/organizations/spend_limits и соблюдает лимиты в реальном времени при каждом запросе вывода. Сами лимиты устанавливаются через этот API, а не в gateway.yaml; каждый запрос POST /v1/organizations/spend_limits создает или заменяет один лимит из {scope, amount, period}. API отражает форматы проводки публичного Admin API Anthropic для лимитов расходов, поэтому HTTP-клиент, написанный для этого контракта, может нацеливаться на gateway, изменив его базовый URL.

Этот запрос устанавливает организационный лимит по умолчанию в размере $500 в месяц для каждого разработчика:

curl -sS https://claude-gateway.internal.example.com/v1/organizations/spend_limits \
  -H "x-api-key: $GATEWAY_ADMIN_WRITE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scope": {"type": "organization"}, "amount": "50000", "period": "monthly"}'

Этот запрос добавляет более строгий лимит в размере $100 в день для каждого члена группы contractors:

curl -sS https://claude-gateway.internal.example.com/v1/organizations/spend_limits \
  -H "x-api-key: $GATEWAY_ADMIN_WRITE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scope": {"type": "rbac_group", "rbac_group_id": "contractors"}, "amount": "10000", "period": "daily"}'

Лимит группы или организации — это лимит по умолчанию на одного пользователя, который наследует каждый член, а не общий пул. За период эффективный лимит разработчика разрешается в этом порядке: переопределение для конкретного пользователя, затем наиболее строгий из его групповых лимитов, затем организационный лимит по умолчанию, затем неограниченно. admin.group_limit_mode: max переключает разрешение конфликта для нескольких групп на наименее строгий вместо этого.

Аутентификация в Admin API

Отправьте одно из следующего:

• Заголовок x-api-key, соответствующий ключу в admin.write_keys для полного доступа или admin.read_keys для доступа только для чтения GET. Каждый ключ имеет id, который появляется в журнале аудита как admin-key:<id>, поэтому дайте Terraform, CI и каждой автоматизации свой собственный.
• Токен bearer gateway, чей claim groups включает одну из admin.admin_groups. Это полный доступ и аудит как oidc:<sub>, поэтому предпочитайте это для администраторов-людей.

Как работает соблюдение

При каждом запросе /v1/messages gateway разрешает лимиты разработчика и расходы с начала периода в одном запросе Postgres. Разработчик, превысивший какой-либо лимит, получает 429 с error.type: billing_error и заголовком x-should-retry: false.

Сообщение указывает период и время сброса, например spend limit reached (daily; resets 2026-08-08 00:00 UTC), за которым следует ваш admin.blocked_message, если установлен. Когда разработчик превышает несколько лимитов одновременно, сообщение указывает лимит, который сбрасывается последним. Ответ также содержит заголовок retry-after с количеством секунд до этого сброса. До версии 2.1.225 на сервере gateway сообщение было spend limit reached без периода, времени сброса или заголовка retry-after.

На версии 2.1.227 или позже справочник протокола по адресу <public_url>/protocol также перечисляет точные заголовки ответа об ограничении использования и тело 429.

Лимиты сбрасываются на границах календаря UTC: ежедневно в 00:00 UTC, еженедельно в понедельник и ежемесячно в первый день. Gateway никогда не блокирует /v1/messages/count_tokens, потому что подсчет токенов бесплатен.

Как оцениваются запросы

После каждого ответа счетчик использования читает количество токенов и добавляет стоимость к ежедневным, еженедельным и ежемесячным счетчикам. Он никогда не трогает байты, отправленные клиенту, поэтому сбой измерения не может нарушить ответ. Суммы являются оценками в USD, автоматическим выключателем, а не счетом; для выставления счетов согласуйте с отчетностью об использовании вашего провайдера.

Счетчик выбирает тарифы каждого запроса в этом порядке:

1. Совпадающая строка pricing.overrides для upstream, который обслужил запрос. Требует версию 2.1.227 или позже.
2. Прайс-лист для ID модели upstream, строка, которую gateway отправляет провайдеру, когда таблица стоимости Claude Code ее распознает. Таблица принимает формы Anthropic, Amazon Bedrock, Google Cloud's Agent Platform и Microsoft Foundry ID.
3. Прайс-лист для models[].id, который вы сопоставили с этим ID upstream, для строк upstream, которые не содержат имя модели, например ARN профиля вывода приложения Amazon Bedrock или имя развертывания Microsoft Foundry. Требует версию 2.1.218 или позже.
4. Уровень неизвестной модели $5/$25 за миллион входных/выходных токенов, поэтому ID, который счетчик не может определить, никогда не бывает бесплатным. Gateway предупреждает при загрузке и один раз за ID во время выполнения, когда использует этот уровень.

Независимо от того, какой тариф применяется, счетчик затем умножает сумму на pricing.multiplier, по умолчанию 1.

Прерывания клиента также учитываются. Когда поток заканчивается без финального кадра использования upstream, счетчик выставляет счет за оценку пола примерно четыре символа на выходной токен для текста, уже отправленного клиенту, поэтому прерывание запросов в начале не позволяет избежать лимита.

Доступность Postgres

Предварительная проверка запрашивает Postgres с двухсекундным тайм-аутом. Если хранилище недоступно или истекает время ожидания, соблюдение по умолчанию не срабатывает: запрос продолжается, gateway регистрирует предупреждение, и ответ не содержит заголовков anthropic-ratelimit-unified-*. Установите enforcement.fail_closed_on_error: true, чтобы вместо этого не срабатывать закрыто, что возвращает то же самое 429 billing_error, но с сообщением spend limit unavailable и без периода, времени сброса или заголовка retry-after. Отказ в открытом виде предотвращает превращение сбоя хранилища в сбой вывода; отказ в закрытом виде гарантирует отсутствие неучтенных расходов.

Предупреждения об использовании в Claude Code

Claude Code предупреждает разработчика по мере приближения к его лимиту: один раз, когда использование превышает 75%, и снова, когда превышает 95% его наиболее потребляемого лимита. Когда gateway блокирует запрос, Claude Code показывает сообщение 429 gateway как есть, включая ваш admin.blocked_message.

Предупреждение работает на основе заголовков ответа:

• С версией 2.1.225 или позже на сервере gateway каждый успешный ответ /v1/messages для разработчика, у которого есть лимит, содержит его собственное использование лимита и время сброса в заголовках anthropic-ratelimit-unified-*.
• С версией 2.1.225 или позже также на машине разработчика Claude Code читает заголовки и показывает предупреждение.

Заголовки всегда описывают лимит самого разработчика: gateway удаляет заголовки ограничения скорости провайдера upstream, которые описывают вашу общую квоту, и никогда их не пересылает.

С версией 2.1.251 или позже на машине разработчика Claude Code также читает те же заголовки для отображения полосы Spend limit в /usage с процентом использованного лимита и временем его сброса, а также для добавления объекта rate_limits.spend_limit в строку статуса ввода. Claude Code показывает оба как процент, а не как сумму в долларах, и не требует ничего новее, чем версия 2.1.225 на сервере gateway.

Справочник Admin API

Конечные точки ниже обслуживаются в /v1/organizations/spend_limits.

Соглашения отражают Admin API Anthropic:

• type на каждом объекте
• ID с префиксом spl_
• Суммы как строки целых чисел в центах USD; POST отклоняет любую другую currency с 400
• Конверт ошибки {type: "error", error: {type, message}, request_id}
• Заголовок ответа request-id при каждом ответе администратора, успехе или ошибке; тела ошибок также содержат его как request_id

Каждая мутация записывает строку до/после в admin_audit в той же транзакции, отнесенную к admin-key:<id> или oidc:<sub>.

Шлюз обслуживает конечные точки лимитов расходов только. Другие поверхности Admin API, такие как очередь spend_limit_increase_requests, не являются частью Admin API шлюза.

`/effective`

GET /v1/organizations/spend_limits/effective возвращает схему SpendSummary Anthropic: каждая строка — это участник за период с разрешенным лимитом, расходами с начала периода и объектом actor. Различия, специфичные для gateway:

• user_id — это OIDC sub.
• actor.name и actor.email_address — это null до первого запроса вывода участника через gateway. Gateway не имеет каталога пользователей; он записывает последние видимые значения из JWT сеанса каждого пользователя.
• Каждая строка также содержит массив groups, последние видимые группы IdP участника. Это расширение gateway, поэтому пользовательский интерфейс администратора может показать каждый уровень лимита, который применяется; клиенты, совместимые с Anthropic, игнорируют это.
• Без фильтра user_ids[] он перечисляет участников с записанными расходами, потому что gateway не может перечислить всех членов организации.

Лимиты на основе групп разрешаются против этих последних видимых групп с тем же разрешением конфликта group_limit_mode, которое использует соблюдение, поэтому средство просмотра показывает применяемый лимит.

`/audit`

Возвращает журнал мутаций лимитов расходов: кто изменил какой лимит, с снимками до/после, самые новые первыми. has_more точен. Эта конечная точка следует локальным соглашениям Admin API, а не форме проводки первой стороны.

Разбиение на страницы

Необработанный список разбивается на страницы по after_id и before_id, которые являются взаимоисключающими ID spl_…; результаты упорядочены по созданию и has_more отражает направление обхода. /effective разбивается на страницы по непрозрачному токену next_page, переданному обратно как ?page=, с участниками, упорядоченными по возрастанию, поэтому страницы остаются стабильными во время записи расходов. limit — это 1–1000, по умолчанию 20, на обоих. /audit разбивается на страницы по after_id, числовому id последнего события на предыдущей странице, и его limit по умолчанию составляет 100.

Жизненный цикл данных

Gateway содержит четыре таблицы, связанные с расходами; почасовая очистка применяет окна удержания:

Когда разработчик уходит, удалите любой лимит для конкретного пользователя через DELETE /v1/organizations/spend_limits/{id}; его расходы и строки идентификации стареют в окнах удержания выше. Чтобы стереть одного человека немедленно, для offboarding или запроса доступа субъекта данных (DSAR), запустите DELETE FROM principal_emails WHERE principal = '<sub>' непосредственно против базы данных gateway. Это удаляет единственную таблицу, содержащую их адрес электронной почты, имя и группы. Строки spend и admin_audit ссылаются только на псевдонимный OIDC sub и стареют в своих собственных окнах.

Связанное

• Конфигурация admin и enforcement: включение Admin API и настройка удержания
• Руководство по развертыванию: схема Postgres и рекомендации по резервному копированию