BerriAI/litellm · error · Exception

Key is blocked. Update via `/key/unblock` if you're an admin

Error message

Key is blocked. Update via `/key/unblock` if you're an admin.

What it means

Hard block on the `blocked` flag of the token: an admin (or a blocking policy) previously disabled this key via `/key/block`, so every request using it fails this base-case check before budgets, models, or teams are even evaluated. Unblocking is deliberately admin-only via `/key/unblock`.

Source

Thrown at litellm/proxy/auth/user_api_key_auth.py:1785

        user_obj: LiteLLM_UserTable | None = None
        valid_token_dict: dict = {}
        if valid_token is not None:
            # Got Valid Token from Cache, DB
            # Run checks for
            # 1. If token can call model
            ## 1a. If token can call fallback models (if client-side fallbacks given)
            # 2. If user_id for this token is in budget
            # 3. If the user spend within their own team is within budget
            # 4. If 'user' passed to /chat/completions, /embeddings endpoint is in budget
            # 5. If token is expired
            # 6. If token spend is under Budget for the token
            # 7. If token spend per model is under budget per model
            # 8. If token spend is under team budget
            # 9. If team spend is under team budget

            ## base case ## key is disabled
            if valid_token.blocked is True:
                raise Exception("Key is blocked. Update via `/key/unblock` if you're an admin.")
            await _enforce_key_and_fallback_model_access(
                valid_token=valid_token,
                request_data=request_data,
                route=route,
                request=request,
                llm_model_list=llm_model_list,
                llm_router=llm_router,
            )

            # Check 2. If user_id for this token is in budget - done in common_checks()
            if valid_token.user_id is not None:
                try:
                    with tracer.trace("litellm.proxy.auth.get_user_object"):
                        user_obj = await get_user_object(
                            user_id=valid_token.user_id,
                            prisma_client=prisma_client,
                            user_api_key_cache=user_api_key_cache,
                            user_id_upsert=False,

View on GitHub (pinned to 77b7c6c40c)

Solutions

If the block was corrective and is resolved, an admin calls `POST /key/unblock` with the key (or its hash)
Otherwise stop using the key: issue a replacement via `/key/generate` and update the client
Audit `/key/info` (admin) to see the blocked state and who/what blocked it before re-enabling

Example fix

# before: service keeps using blocked key -> exception on every call
client = OpenAI(base_url=..., api_key=blocked_key)

# after: admin restores
admin.post("/key/unblock", json={"key": key_hash})
# or rotate: new_key = admin.post("/key/generate", json={...}).json()["key"]

Defensive patterns

Strategy: try-catch

Validate before calling

# admin pre-flight before a critical run
info = admin.post("/key/info", json={"keys": [hash_key(key)]}).json()
if info["info"][0].get("blocked"):
    admin.post("/key/unblock", json={"key": hash_key(key)})  # if legitimately restorable

Try / catch

try:
    resp = client.chat.completions.create(...)
except Exception as e:
    if "Key is blocked" in str(e):
        notify_admin(f"key {alias} blocked — unblock via /key/unblock or rotate")
        raise KeyBlocked(alias) from e
    raise

Prevention

After any leak response, rotate clients off blocked keys instead of retrying
Alert on blocked-key errors so owners learn the key needs replacement
Document the /key/unblock runbook for admins

When it happens

Trigger: Using a key after `POST /key/block {"key": ...}` (e.g. quarantine of a leaked key, offboarding a contractor); keys auto-blocked by incident response; leftover creds in a service after security rotation.

Common situations: Leaked-key response blocking the compromised key while the leaking service keeps retrying; offboarding a user but their CI job still runs; blocked key alias reused by another team unaware of the block; testing whether a key works after a security event.

Related errors

AI-assisted analysis of BerriAI/litellm@77b7c6c40c (2026-08-18). Data as JSON: /api/errors/cb991a7660a47323. Report an issue: GitHub.