{"record":{"id":"99eb6d436b4de94d","repo":"BerriAI/litellm","slug":"generic-guardrail-api-failed-error","errorCode":null,"errorMessage":"Generic Guardrail API failed: {error}","messagePattern":"Generic Guardrail API failed: (.+?)","errorType":"exception","errorClass":"Exception","httpStatus":null,"severity":"error","filePath":"litellm/proxy/guardrails/guardrail_hooks/generic_guardrail_api/generic_guardrail_api.py","lineNumber":360,"sourceCode":"        self,\n        error: Exception,\n        inputs: GenericGuardrailAPIInputs,\n        input_type: Literal[\"request\", \"response\"],\n        logging_obj: Optional[\"LiteLLMLoggingObj\"],\n        is_unreachable: bool = True,\n    ) -> GenericGuardrailAPIInputs:\n        unreachable_fail_open: Final = is_unreachable and self.unreachable_fallback == \"fail_open\"\n        if unreachable_fail_open or not self.fail_on_error:\n            http_status_code: Final = getattr(getattr(error, \"response\", None), \"status_code\", None)\n            return self._fail_open_passthrough(\n                inputs=inputs,\n                input_type=input_type,\n                logging_obj=logging_obj,\n                error=error,\n                **({\"http_status_code\": http_status_code} if http_status_code else {}),\n            )\n        verbose_proxy_logger.error(\"Generic Guardrail API: failed to make request: %s\", str(error))\n        raise Exception(f\"Generic Guardrail API failed: {error}\")\n\n    @log_guardrail_information\n    async def apply_guardrail(\n        self,\n        inputs: GenericGuardrailAPIInputs,\n        request_data: dict,\n        input_type: Literal[\"request\", \"response\"],\n        logging_obj: Optional[\"LiteLLMLoggingObj\"] = None,\n    ) -> GenericGuardrailAPIInputs:\n        \"\"\"\n        Apply the Generic Guardrail API to the given inputs.\n\n        This is the main method that gets called by the framework.\n\n        Args:\n            inputs: Dictionary containing:\n                - texts: List of texts to check\n                - images: Optional list of images to check","sourceCodeStart":342,"sourceCodeEnd":378,"githubUrl":"https://github.com/BerriAI/litellm/blob/77b7c6c40c0c5aa5fbcb1d6a1825ac39ca8829b8/litellm/proxy/guardrails/guardrail_hooks/generic_guardrail_api/generic_guardrail_api.py#L342-L378","documentation":"Bare Exception raised in GenericGuardrailAPI._handle_guardrail_request_error when the guardrail call fails and neither fail-open branch applies: i.e. the error is not an unreachable-502/503/504 with unreachable_fallback='fail_open', and fail_on_error is True (its default). It wraps Timeout, HTTPStatusError (any status, including 401/403/404/429), RequestError, and unexpected exceptions from payload building. Note this is a plain Exception, not a dedicated error class.","triggerScenarios":"Guardrail service returns 401/403 (bad x-api-key), 404 (wrong path after suffix append), 429, or any 5xx with unreachable_fallback='fail_closed'; connection refused/timeout to api_base; pydantic validation failure while building GenericGuardrailAPIRequest.","commonSituations":"Custom guardrail service down or scaled to zero; API key header format changed; api_base pointing at the wrong path so the auto-appended /beta/litellm_basic_guardrail_api 404s; fail_on_error left at default true making the guardrail availability gate all LLM traffic.","solutions":["Check the proxy log 'Generic Guardrail API: failed to make request: <error>' for the underlying cause and status.","Curl your service at {api_base}/beta/litellm_basic_guardrail_api with the same x-api-key header to verify reachability and auth.","Set fail_on_error: false in litellm_params so guardrail failures pass traffic through (fail-open on any error).","For outages only, set unreachable_fallback: fail_open to fail-open specifically on 502/503/504 while still failing on auth errors.","Confirm api_base is the service root; the endpoint path is appended automatically."],"exampleFix":"# before\nlitellm_params:\n  guardrail: generic_guardrail_api\n  api_base: os.environ/GENERIC_GUARDRAIL_API_BASE\n  # fail_on_error defaults to true\n\n# after\nlitellm_params:\n  guardrail: generic_guardrail_api\n  api_base: os.environ/GENERIC_GUARDRAIL_API_BASE\n  fail_on_error: false","handlingStrategy":"fallback","validationCode":"import httpx, os\n\nbase = os.getenv('GENERIC_GUARDRAIL_API_BASE')\nif base:\n    r = httpx.get(f\"{base.rstrip('/')}/health\", timeout=5)  # adjust to your service's health route\n    assert r.status_code < 500, f'guardrail service unhealthy: {r.status_code}'","typeGuard":null,"tryCatchPattern":"try:\n    result = await guardrail.apply_guardrail(inputs, request_data, input_type, logging_obj)\nexcept Exception as e:  # generic guardrail raises a bare Exception\n    if 'Generic Guardrail API failed' in str(e):\n        logger.warning('generic guardrail failed, failing open: %s', e)\n        result = dict(inputs)\n    else:\n        raise","preventionTips":["Set fail_on_error: false (and/or unreachable_fallback: fail_open) unless fail-closed is mandated.","Health-check the guardrail service from the proxy's network path in your readiness probe.","Alert on 'failed to make request' log lines to catch auth/path regressions early."],"tags":["generic-guardrail","guardrail","http-error","fail-closed","network"],"backgroundTag":"guardrail-api-request-failed","analyzedSha":"77b7c6c40c0c5aa5fbcb1d6a1825ac39ca8829b8","analyzedAt":"2026-08-18T11:44:31.656Z","schemaVersion":2},"datasetVersion":"2026-08-22T04:17:13.399Z"}