> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.joytokens.ai/llms.txt.

# Guardrails

> Control source, model, tier, and budget with API key policy

Guardrails limit where an API key can be used, which tiers and auto-routing candidates it can access, and how much it can spend.

## Recommended Setup

| Scenario                    | Recommendation                                |
| --------------------------- | --------------------------------------------- |
| Local development           | Separate key, small budget, start with `auto` |
| Development backend         | IP allowlist, explicit tier, budget limit     |
| Coding agent / IDE          | Dedicated key, small daily or weekly budget   |
| High-risk agent             | Key budget plus app-side stop conditions      |
| Stable development workflow | fixed tier and key budget                     |

## Available Limits

| Limit                    | Use                                         |
| ------------------------ | ------------------------------------------- |
| IP allowlist / blocklist | Restrict request source                     |
| allowed tiers            | Restrict `economy` / `standard` / `premium` |
| model blacklist          | Exclude models from automatic routing       |
| daily / weekly budget    | Limit period spend                          |
| routing strategy         | Control auto-routing preference             |

## Rejected Requests

| Error                    | Common cause                                    |
| ------------------------ | ----------------------------------------------- |
| `403 invalid_api_key`    | Key is invalid, revoked, expired, or not active |
| `403 policy_rejected`    | IP, tier, blacklist, or blocked policy failed   |
| `402 insufficient_quota` | Wallet balance, budget, or pre-freeze failed    |

## Change Policy

Use a new key to replace the old key:

1. Create a new key with the new policy.
2. Send a test request with `X-Request-ID`.
3. Confirm logs and usage in JoyToken Console.
4. Switch environment variables.
5. Revoke the old key after observation.