Los límites de gasto limitan cuánto puede gastar cada desarrollador a través de su puerta de enlace de aplicaciones Claude en un día, semana o mes determinado. Cuando un desarrollador supera su límite, la puerta de enlace devuelve 429 en su siguiente solicitud y lo bloquea hasta que el período se reinicie o un administrador aumente el límite. Utilice límites de gasto para dar a cada desarrollador, grupo u organización completa un techo en una credencial que todos comparten.
Una puerta de enlace de aplicaciones Claude reenvía toda la inferencia a través de una credencial ascendente compartida, por lo que la factura de su proveedor atribuye todo a esa credencial, no a desarrolladores individuales. Sin límites por desarrollador, una flota de agentes descontrolada puede gastar todo el compromiso de la organización. Los límites de gasto son la vista por desarrollador de la puerta de enlace y el disyuntor en la parte superior de esa factura compartida.
Establecer un límite
Con el bloque admin: configurado en gateway.yaml, la puerta de enlace sirve una API de administrador en /v1/organizations/spend_limits y aplica límites en vivo en cada solicitud de inferencia. Los límites en sí se establecen a través de esa API, no en gateway.yaml; cada solicitud POST /v1/organizations/spend_limits crea o reemplaza un límite de {scope, amount, period}. La API refleja las formas de cable de los puntos finales de límites de gasto de la API de administrador pública de Anthropic, por lo que un cliente HTTP escrito contra ese contrato puede dirigirse a la puerta de enlace cambiando su URL base.
Esta solicitud establece un valor predeterminado de toda la organización de $500 por mes para cada desarrollador:
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"}'
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"}'
| Campo | Valores | Descripción |
|---|
scope.type | user, rbac_group, organization | user se dirige a un desarrollador por su OpenID Connect (OIDC) sub, el ID de usuario estable que asigna su proveedor de identidad; páselo como scope.user_id. rbac_group se dirige a un grupo de IdP por nombre; páselo como scope.rbac_group_id. organization es el valor predeterminado de toda la organización. La puerta de enlace acepta los tres; el POST público de Anthropic es solo para usuarios hoy. |
amount | Cadena de número entero de centavos USD, o null | null es ilimitado. "0" es un límite cero, que bloquea cada solicitud. |
period | daily, weekly, monthly | Un ámbito puede contener un límite por período, y cada uno se aplica de forma independiente: un desarrollador se bloquea si supera cualquiera de ellos. |
admin.group_limit_mode: max invierte el desempate de múltiples grupos a menos restrictivo en su lugar.
Autenticarse en la API de administrador
Envíe uno de:
- Un encabezado
x-api-key que coincida con una clave en admin.write_keys para acceso completo, o admin.read_keys para acceso de solo GET. Cada clave lleva un id que aparece en el registro de auditoría como admin-key:<id>, así que dé a Terraform, CI y cada automatización la suya propia.
- Un token de portador de puerta de enlace cuya reclamación
groups incluya uno de admin.admin_groups. Este es acceso completo y se audita como oidc:<sub>, así que prefieralo para administradores humanos.
Cómo funciona la aplicación
En cada solicitud /v1/messages, la puerta de enlace resuelve los límites del desarrollador y el gasto hasta la fecha del período en una consulta de Postgres. Si superan cualquier límite, la solicitud devuelve 429 con error.type: billing_error y el encabezado x-should-retry: false. El mensaje es spend limit reached, seguido de su admin.blocked_message si se establece.
/v1/messages/count_tokens está exento. El conteo de tokens es gratuito, por lo que se ejecuta independientemente del estado del límite.
Después de cada respuesta, un medidor de uso lee los conteos de tokens de la respuesta mientras se transmite al cliente, los precifica al precio de lista USD y incrementa los contadores de Postgres para los tres depósitos de período. El medidor es un lector único en la transmisión, por lo que los bytes del cliente no se tocan y una falla de medición no rompe la respuesta.
Los límites de gasto estiman el gasto a partir de conteos de tokens al precio de lista USD; son un disyuntor, no una factura. Para facturación autorizada, reconcilie contra el informe de uso de su propio proveedor, como la API de administrador de uso y costo de Anthropic, registros de invocación en Bedrock o monitoreo en la nube en Google Cloud.
La fijación de precios utiliza la misma tabla que la CLI de Claude Code utiliza para su propia visualización de costos, con la misma canonicalización de ID de modelo en formularios de Anthropic, Bedrock (us.anthropic.…-v1:0), Agent Platform (claude-…@date) y Foundry ID. Un ID de modelo que la tabla no puede colocar, como un nombre de implementación de Foundry o un ARN de perfil de inferencia, se precifica en el nivel predeterminado de modelo desconocido de $5/$25 por millón de tokens de entrada/salida en lugar de cero, por lo que un ID no reconocido no puede eludir un límite al no ser medido. La puerta de enlace advierte al arrancar y una vez por ID en tiempo de ejecución cuando un modelo se precifica a través de la alternativa.
Los abortos de cliente también se facturan. El ascendente informa tokens de salida solo en el marco terminal de la transmisión, por lo que una transmisión abortada no los lleva. El medidor mantiene una estimación de piso conservadora del tamaño del contenido transmitido, aproximadamente cuatro caracteres por token, y la factura cuando y solo cuando falta el marco de uso terminal. Una transmisión completa siempre factura el conteo informado por el ascendente. Sin esto, un desarrollador limitado podría transmitir salida y abortar cada solicitud inmediatamente antes del final, gastando sin nunca ser contado.
Disponibilidad de Postgres
La consulta previa consulta Postgres con un tiempo de espera de dos segundos. Si el almacén es inaccesible o agota el tiempo de espera, la aplicación falla abierta de forma predeterminada: la solicitud continúa y la puerta de enlace registra una advertencia. Establezca enforcement.fail_closed_on_error: true para fallar cerrado en su lugar, que devuelve el mismo 429 billing_error con el mensaje spend limit unavailable. Fallar abierto evita que una interrupción del almacén se convierta en una interrupción de inferencia; fallar cerrado garantiza que no haya gasto sin medidor.
Referencia de API de administrador
Los puntos finales a continuación se sirven bajo /v1/organizations/spend_limits.
| Método y ruta | Descripción |
|---|
GET /v1/organizations/spend_limits | Enumera los límites configurados. Consulta: ?limit=&after_id=&before_id=. |
POST /v1/organizations/spend_limits | Crea o reemplaza un límite para {scope, period}. |
GET /v1/organizations/spend_limits/{id} | Obtiene un límite por su ID con prefijo spl_. |
DELETE /v1/organizations/spend_limits/{id} | Elimina un límite. Devuelve {type: "spend_limit_deleted", id}. |
GET /v1/organizations/spend_limits/effective | Límite resuelto y gasto hasta la fecha por principal por período. |
GET /v1/organizations/spend_limits/audit | Registro de mutación de administrador, más reciente primero. Consulta: ?limit=. |
- Un
type en cada objeto
- IDs con prefijo
spl_
- Cantidades como cadenas de número entero de centavos USD;
POST rechaza cualquier otro currency con 400
- El sobre de error
{type: "error", error: {type, message}, request_id}
- Un encabezado de respuesta
request-id en cada respuesta de administrador, éxito o error, que coincida con el request_id del cuerpo
Cada mutación escribe una fila antes/después en admin_audit en la misma transacción, atribuida a admin-key:<id> u oidc:<sub>.
La puerta de enlace sirve solo los puntos finales de límites de gasto. Otras superficies de API de administrador, como la cola spend_limit_increase_requests, no son parte de la API de administrador de la puerta de enlace.
/effective
GET /v1/organizations/spend_limits/effective devuelve el esquema SpendSummary de Anthropic: cada fila es un principal para un período, con el límite resuelto, gasto hasta la fecha del período y un objeto actor. Diferencias específicas de la puerta de enlace:
user_id es el OIDC sub.actor.name y actor.email_address son null hasta la primera solicitud de inferencia del principal a través de la puerta de enlace. La puerta de enlace no tiene directorio de usuarios; registra valores vistos por última vez desde el JWT de sesión de cada usuario.- Cada fila también lleva una matriz
groups, los últimos grupos de IdP vistos del principal. Esta es una extensión de puerta de enlace para que una interfaz de usuario de administrador pueda mostrar cada nivel de límite que se aplica; los clientes con forma de Anthropic la ignoran.
- Sin un filtro
user_ids[], enumera principales con gasto registrado, porque la puerta de enlace no puede enumerar todos los miembros de la organización.
Los límites originados en grupos se resuelven contra esos últimos grupos vistos con el mismo desempate group_limit_mode que usa la aplicación, por lo que el visor muestra el límite que realmente se aplica.
| Parámetro de consulta | Descripción |
|---|
user_ids[] | Repetible. Filtrar a principales específicos por OIDC sub. |
period[] | Repetible. Filtrar a filas daily, weekly o monthly. |
sort | spend_desc enumera los principales con mayor gasto primero. Requiere exactamente un period[]. |
q | Filtro de subcadena que no distingue mayúsculas de minúsculas sobre el OIDC sub, correo electrónico visto por última vez y nombre para mostrar visto por última vez. |
limit / page | Tamaño de página, 1–1000 con un predeterminado de 20, y el cursor opaco de la respuesta anterior next_page. |
q= y user_ids[]= montan cadenas de consulta GET, por lo que cualquier proxy frontal o equilibrador de carga los captura en sus registros de acceso. Si su política de registro de PII es estricta, depure estos parámetros allí.
/audit
Devuelve el registro de mutación de límite de gasto: quién cambió qué límite, instantáneas antes/después y la razón opcional, más reciente primero. has_more es exacto. Este punto final sigue las convenciones de API de administrador local en lugar de una forma de cable de primera parte.
La lista sin procesar pagina por after_id y before_id, que son IDs spl_… mutuamente excluyentes; los resultados se ordenan por creación y has_more refleja la dirección del recorrido. /effective pagina por el token opaco next_page pasado de vuelta como ?page=, con principales ordenados ascendentemente para que las páginas se mantengan estables mientras se registra el gasto. limit es 1–1000, predeterminado 20, en ambos.
Ciclo de vida de datos
La puerta de enlace contiene cuatro tablas relacionadas con el gasto; un barrido cada hora aplica las ventanas de retención:
| Tabla | Contenidos | Retención |
|---|
spend | Contadores hasta la fecha del período por principal en centavos | admin.spend_retention_months, predeterminado 13 |
spend_limits | Los límites configurados | Hasta eliminarse a través de la API |
admin_audit | El registro de mutación | admin.audit_retention_days, predeterminado 365 |
principal_emails | Correo electrónico visto por última vez de cada principal, nombre para mostrar y grupos de IdP. Contiene PII. | admin.identity_retention_days desde la última actividad, predeterminado 90 |
identity_retention_days es deliberadamente más corto que spend_retention_months: una identidad desaprovisionada deja de actualizarse y envejece, mientras que sus contadores de gasto anónimos permanecen para informes año tras año.
Cuando un desarrollador se va, elimine cualquier límite por usuario a través de DELETE /v1/organizations/spend_limits/{id}; sus filas de gasto e identidad envejecen en las ventanas de retención anteriores. Para borrar una persona inmediatamente, para desincorporación o una solicitud de acceso de sujeto de datos (DSAR), ejecute DELETE FROM principal_emails WHERE principal = '<sub>' directamente contra la base de datos de la puerta de enlace. Eso elimina la única tabla que contiene su correo electrónico, nombre y grupos. Las filas spend y admin_audit hacen referencia solo al sub OIDC seudónimo y envejecen en sus propias ventanas.
