BerriAI/litellm · error · HTTPException

Content blocked: {category_name} conditional match '{matched

Error message

Content blocked: {category_name} conditional match '{matched_phrase}' detected (severity: {severity})

What it means

HTTPException(400) raised by _handle_conditional_match when a conditional category phrase matches and the effective action is BLOCK. Conditional categories only trigger on a phrase when a related category keyword was also detected in the text (e.g. 'card' matters only alongside a credit-card keyword), and the severity from the category config is embedded in the message. Note the source logs that MASK is not supported for conditional categories — the only outcomes are block or log-and-continue.

Source

Thrown at litellm/proxy/guardrails/guardrail_hooks/litellm_content_filter/content_filter.py:1228

        detections: list[ContentFilterDetection] | None,
    ) -> None:
        """Handle conditional category match detection and action."""
        if detections is not None:
            category_detection: Final[CategoryKeywordDetection] = {
                "type": "category_keyword",
                "category": category_name,
                "keyword": matched_phrase,
                "severity": severity,
                "action": action.value,
            }
            detections.append(category_detection)

        if action == ContentFilterAction.BLOCK:
            error_msg: Final = (
                f"Content blocked: {category_name} conditional match '{matched_phrase}' detected (severity: {severity})"
            )
            verbose_proxy_logger.warning(error_msg)
            raise HTTPException(
                status_code=400,
                detail={
                    "error": error_msg,
                    "category": category_name,
                    "matched_phrase": matched_phrase,
                    "severity": severity,
                },
            )
        elif action == ContentFilterAction.MASK:
            verbose_proxy_logger.warning(
                "Conditional match '%s' from %s detected but MASK action not supported for conditional categories",
                matched_phrase,
                category_name,
            )

    def _handle_category_keyword_match(
        self,
        keyword: str,

View on GitHub (pinned to 77b7c6c40c)

Solutions

Inspect the 400 detail: category, matched_phrase, and severity tell you exactly which conditional rule fired.
Tune the category YAML: raise the severity threshold, remove/adjust the conditional phrase, or change that match's action so it no longer blocks.
Handle it client-side as a policy rejection — do not retry the same content.
Sanitize or rephrase the input to break the keyword+phrase combination.

Defensive patterns

Strategy: try-catch

Try / catch

from fastapi import HTTPException

def is_conditional_filter_block(exc: HTTPException) -> bool:
    d = exc.detail if isinstance(exc.detail, dict) else {}
    return (
        exc.status_code == 400
        and str(d.get("error", "")).startswith("Content blocked:")
        and "conditional match" in str(d.get("error", ""))
    )

try:
    resp = await client.chat.completions.create(**params)
except HTTPException as e:
    if is_conditional_filter_block(e):
        raise PolicyRejectedError(
            user_message="Request blocked by content policy",
            internal_detail=e.detail,  # category/matched_phrase/severity — log only
        ) from e
    raise

Prevention

Remember MASK is unsupported for conditional categories — only tune thresholds/phrases/actions to soften them.
Test representative traffic against enabled categories in staging; conditional rules surprise with keyword+phrase combos.
Raise severity_threshold in the guardrail config to skip low-severity conditional matches entirely.
Map the 400 to a non-retryable client error; the same input always blocks again.

When it happens

Trigger: A guarded request's text contains both the conditional category's keyword and its conditional phrase, the category file's action (or default_action) for that match is BLOCK, and the severity threshold is met.

Common situations: False positives where innocuous text accidentally combines a keyword and a phrase; strict severity thresholds in the shipped category templates; testing real user prompts against a newly enabled category.

Related errors

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