Policies

A policy decides what a request may do. The gateway evaluates it before any provider is called and refuses the request with a clear code when it breaks a rule.

What you can restrict

• Models: allowed_models
• Providers: allowed_providers
• Regions: allowed_regions (matched against each deployment's region_name or aws_region_name)
• Output size: max_tokens
• External providers: allow_external: false limits callers to models marked model_info: {internal: true}
• Caching: cache_ttl

Scopes

Policies can be set at the default, domain, organisation, team and key level, and the most restrictive result applies. See Policy File.

Teams, keys and domains come from the caller's virtual key on the server. In the SDK you pass them as team=, key= and domain=.

Named policies and attachments

Define a policy once and attach it by pattern:

policies:
  phi-strict:
    max_tokens: 2000
    guardrails: {add: [pii-strict, claims-phi]}

policy_attachments:
  - {policy: phi-strict, teams: ["claims-*"]}

Refusals

Situation	HTTP	code
Model not allowed	403	policy_violation
Provider or region not allowed	403	policy_violation
External provider forbidden	403	policy_violation
max_tokens over the limit	400	max_tokens_exceeded
Unknown domain	403	unknown_domain
No routing rule can serve the request	403 or 400	no_route
Budget used up	402	budget_exceeded

In the SDK these become PolicyViolation and BudgetExceeded, both subclasses of GatewayDenied carrying status_code, code and message.

Fallbacks respect policy

If a model fails and LiteLLM would fall back to another, a fallback the caller's policy forbids is dropped. A downgraded model is still checked against the policy.

Caller identity

Value	Source, most trusted first
User	A key scoped to a user, then the X-User-Id header, then the OpenAI user field
Agent	A key scoped to an agent, then the X-Agent-Id header

For keys that are not user-scoped, the id is an assertion by the calling application. The gateway records it and enforces budgets on it but cannot verify it.