What causes "Cisco AI Defense {surface} API request failed: {exc}" in BerriAI/litellm?

Test raw reachability from the proxy host: curl -v $CISCO_AI_DEFENSE_API_BASE — fix DNS/firewall/egress based on the failure mode.

BerriAI/litellm · error · CiscoAIDefenseGuardrailAPIError

Cisco AI Defense {surface} API request failed: {exc}

Error message

Cisco AI Defense {surface} API request failed: {exc}

What it means

CiscoAIDefenseGuardrailAPIError raised when httpx raises a RequestError that is not a timeout — connection refused/reset, DNS resolution failure, TLS certificate error, or proxy negotiation failure while reaching the Cisco AI Defense API base. The underlying exception text ({exc}) names the exact network fault, and it is chained as __cause__.

Source

Thrown at litellm/proxy/guardrails/guardrail_hooks/cisco_ai_defense/cisco_ai_defense.py:838

                follow_redirects=False,
            )
            response.raise_for_status()
        except httpx.HTTPStatusError as exc:
            status_code: Final = exc.response.status_code if exc.response is not None else 0
            body_snippet = ""
            try:
                body_snippet = exc.response.text[:500] if exc.response else ""
            except Exception:
                body_snippet = ""
            raise CiscoAIDefenseGuardrailAPIError(
                f"Cisco AI Defense {surface} API returned HTTP {status_code}: {body_snippet}"
            ) from exc
        except httpx.TimeoutException as exc:
            raise CiscoAIDefenseGuardrailAPIError(
                f"Cisco AI Defense {surface} API call timed out after {self.timeout}s"
            ) from exc
        except httpx.RequestError as exc:
            raise CiscoAIDefenseGuardrailAPIError(f"Cisco AI Defense {surface} API request failed: {exc}") from exc

        try:
            return response.json()
        except ValueError as exc:
            raise CiscoAIDefenseGuardrailAPIError(
                f"Cisco AI Defense {surface} API returned a non-JSON response"
            ) from exc

    def _build_headers(self) -> dict[str, str]:
        return {
            CISCO_API_KEY_HEADER: self.api_key,
            "Content-Type": "application/json",
            "Accept": "application/json",
            "User-Agent": f"litellm/{litellm_version}",
        }

    def _build_metadata(
        self,

View on GitHub (pinned to 77b7c6c40c)

Solutions

Test raw reachability from the proxy host: curl -v $CISCO_AI_DEFENSE_API_BASE — fix DNS/firewall/egress based on the failure mode.
If behind a TLS-intercepting proxy, mount the corporate CA or configure httpx SSL context appropriately.
Fix or unset a wrong CISCO_AI_DEFENSE_API_BASE so the default official endpoint is used.
Set fallback_on_error: allow to keep traffic flowing (unscanned, logged) when the inspection endpoint is unreachable.

Example fix

# before — unreachable Cisco endpoint breaks all LLM calls
litellm_params:
  guardrail: cisco_ai_defense

# after — proceed unscanned when the guardrail network path fails
litellm_params:
  guardrail: cisco_ai_defense
  fallback_on_error: allow

Defensive patterns

Strategy: retry

Validate before calling

import httpx, os
base = os.environ.get("CISCO_AI_DEFENSE_API_BASE") or "<default>"
try:
    httpx.get(base, timeout=5)
except httpx.ConnectError as e:
    raise SystemExit(f"Cisco endpoint unreachable from this host: {e}")
except httpx.ConnectTimeout:
    raise SystemExit("Cisco endpoint connect timeout — check egress/firewall")

Try / catch

try:
    resp = litellm.completion(...)
except Exception as e:
    cause = getattr(e, "__cause__", None)
    if isinstance(cause, httpx.ConnectError):
        log_network_issue(cause); retry_once_later()  # transient reset/DNS
    elif isinstance(cause, httpx.ConnectTimeout):
        alert_egress_blocked()
    raise

Prevention

Run a connectivity smoke test from the exact proxy runtime (container, not dev laptop) before enabling.
Whitelist Cisco domains in egress firewalls / NetworkPolicies explicitly.
Mount corporate CA bundles into containers when TLS-intercepting proxies are in path.
fallback_on_error: allow decouples LLM availability from scanner network health.

When it happens

Trigger: Inspect calls failing before any HTTP status exists: wrong CISCO_AI_DEFENSE_API_BASE hostname (NXDOMAIN), firewall/egress rules blocking the Cisco domain, corporate MITM proxy with an untrusted CA, TLS mismatches, or connection resets during network flaps.

Common situations: Containers without corporate CA bundles failing TLS to TLS-intercepting proxies; staging environments with no outbound internet; api_base typos (cisco.example vs real host); Kubernetes NetworkPolicies blocking egress; transient DNS failures in large deployments.

Related errors

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