Gateway Limits And Guardrails

• Usage limits decide whether the project API key may consume more requests, tokens, or cost.
• Guardrails inspect the request or response and monitor, adjust, or block supported conditions.

Both controls produce structured project evidence: usage-policy events or guardrail trace events. Neither replaces application authorization or provider-side safety controls.

Provon Cloud managed targets also use an organization credit ledger. Credits pay for managed model execution; they are not a third project policy layer.

Usage Limits#

Usage limits bound how much a Gateway workload can consume. A limit is scoped to an organization, project, or API key, and can optionally be narrowed to a specific request model ID. The runtime checks all matching limits before routing and rejects the request when any limit would be exceeded.

Limit Scopes#

The narrowest matching scope wins first. For example, a model_per_api_key limit on openai/gpt-5-mini is checked independently from a project-level token budget.

Metrics And Modes#

Supported metrics:

Supported windows are minute, hour, day, week, month, quarter, year, custom, and lifetime.

Configure A Limit#

In the Workbench:

1. Open API keys.
2. Expand the project key used by the workload.
3. Under Limits, select Add limit.
4. Choose metric, type, limit, period, and scope.
5. For a model-specific scope, enter the exact request model ID.
6. Save the limit and monitor used, reserved, remaining, and reset values.

Provon reserves estimated usage before routing, then settles successful requests against actual usage when the provider reports it. Failed requests release their reservation.

Rejection Contract#

When admission would exceed a policy, Gateway returns 429:

{
  "error": {
    "code": "gateway_budget_exceeded",
    "message": "Gateway budget exceeded",
    "reason": "cost_budget_exceeded",
    "policyId": "policy_123",
    "resetAt": "2026-08-02T00:00:00.000Z"
  }
}

Rate-limit rejections use rate_limit_exceeded. Responses include:

Retry-After
RateLimit-Limit
RateLimit-Remaining
RateLimit-Reset

Do not implement automatic retries for a cost or lifetime budget rejection. Retry only when the policy has a reset time and the workload can wait.

Cloud AI Gateway Credits#

Provon Cloud managed model targets use the organization's prepaid Cloud AI Gateway credits. This ledger is separate from project API-key usage limits:

• credits pay for managed provider execution;
• API-key limits bound one workload's requests, tokens, or cost;
• BYOK requests use the upstream provider account instead of the Provon Cloud credit balance.

Provon reserves an estimated amount before a managed request and settles against actual model usage afterward. Insufficient balance returns 402:

{
  "error": {
    "code": "INSUFFICIENT_GATEWAY_CREDITS",
    "message": "organization does not have enough Cloud AI Gateway credits"
  }
}

Add credit under organization Billing. Do not retry until the balance changes or the request is moved intentionally to a BYOK target.

Guardrail Modes And Actions#

Guardrails are configured under Guardrails and run in priority order.

Modes#

Actions#

When a rule matches in Enforce mode, Provon can take one of the following actions:

Start new rules with Monitor against representative traffic. Review the captured match evidence before switching to Adjust, Block, Abort stream, or Stop retry.

In Monitor mode the trace still records the action the rule would have taken, so you can audit false positives before enforcement.

Built-In Guardrails#

Data Protection#

These rules support monitoring, redaction through Adjust, and blocking. Match evidence stores categories and hashes rather than the matched secret value.

Tool Governance#

Tool argument policies support wildcard tool names and optional argument-path predicates. Use them to enforce explicit application policy, not to infer business authorization from prompt text.

Context Budget#

Input token checks are estimates. API-key token policies perform their own admission reservation and settle against provider-reported usage when available.

Guardrail Block Contract#

An enforced block returns 409:

{
  "error": {
    "message": "Provon Gateway blocked this exchange because a guardrail was triggered.",
    "type": "provon_gateway_guard",
    "code": "PROVON_GATEWAY_GUARD_TRIGGERED",
    "param": null,
    "retryable": false,
    "details": {
      "pluginId": "provon.guard.secret-leak",
      "action": "block",
      "direction": "input",
      "category": "openai_api_key"
    }
  }
}

The response includes:

x-provon-guard-triggered: true
x-provon-guard-plugin-id
x-provon-guard-action
x-provon-request-id

Do not retry the same blocked payload. Change the request or the project policy.

Tool Argument Policies#

Each Tool argument policy rule matches:

• a tool-name pattern;
• an optional argument field path;
• an operator;
• an optional comparison value;
• an optional reason and category.

Supported operators include existence, equality, numeric comparison, string containment, prefix/suffix matching, and allow/deny list membership.

Example intent:

tool pattern: shell_*
field:        command
operator:     contains
value:        rm -rf
action:       Block

Keep tool authorization in the application. A Gateway guardrail is an additional policy boundary, not the source of user permissions.

Layering Controls#

Apply controls in this order:

1. Use application authentication and authorization for user actions.
2. Restrict project API-key capabilities and rotate keys independently.
3. Add API-key usage limits for hard resource boundaries.
4. Add guardrails for request, response, and tool-shape policy.
5. Restrict Provider Keys and model mappings to approved upstream targets.
6. Use Trace Capture to retain the evidence needed to audit decisions.

A request may be admitted by usage policy and still be blocked by a guardrail. A request may pass both and still fail provider authentication, capability checks, or upstream execution.

Security Guidance#

• Give workloads Provon project keys, never upstream provider keys.
• Use a separate project key per environment or application boundary.
• Avoid raw secrets and unnecessary personal data in prompts and context headers.
• Use Specific model mappings when a Provider Key must expose a strict allowlist.
• Treat header overrides and custom upstream URLs as privileged configuration.
• Review Provider Key, guardrail, and API-key changes as production policy changes.
• Apply project telemetry retention to captured prompts, responses, and tool arguments.