Failure Modes

OGuardAI fails closed by default: when protection cannot be enforced, the request fails rather than returning unprotected text. The one deliberate exception is both mode, which is explicitly best-effort: on an NER outage it falls back to builtin regex detection and continues with reduced coverage. advanced mode fails closed instead, rejecting the request when NER is unavailable. See the matrix below for the exact behavior per failure.

Failure Matrix

Degradation Flow

Degradation Matrix

What still works when a component is unavailable:

"Partial" means the operation succeeds but with reduced entity coverage: the NER-only types (person, company, location) drop out, while the builtin regex and custom-pattern types still resolve. "Degraded" means the operation succeeds but with reduced durability or consistency.

Design Principles

1. Never return unprotected text. If detection cannot run, the request fails rather than passing raw PII through.
2. Cryptographic verification on every unseal. Tampered or expired session blobs are always rejected.
3. Stateless by default. The sealed session model has no external dependencies for a single instance. Redis and file backends are optional there, but a multi-replica deployment requires shared Redis revocation (revocation_backend=redis) so a value revoked on one replica is refused by all.
4. NER failure behavior depends on mode. In both mode, NER unavailability falls back to builtin (fail-open), unless the policy requires an NER-backed type, in which case the request fails closed with GUARDAI_DETECTION_UNAVAILABLE (503, retriable). In advanced mode, NER is required: a sidecar outage (unreachable, transport error, timeout, or a degraded response) fails closed with the same GUARDAI_DETECTION_UNAVAILABLE (503, retriable), while GUARDAI_DETECTION_FAILED (500) is reserved for a genuine capability rejection (the sidecar responded but cannot serve the required labels). Monitor GUARDAI_DETECTION_UNAVAILABLE for sidecar outages.
5. Revoked values are permanently suppressed. Even if the session blob is valid, revoked entities always return [DELETED].

Monitoring Recommendations

• Poll /v1/capabilities periodically. The ner_active field reflects the configured detector mode (not live sidecar status). For sidecar outages, use guardai_ner_degraded_total together with the error_code = GUARDAI_DETECTION_UNAVAILABLE log events (an advanced-mode detector error logs GUARDAI_DETECTION_FAILED instead). See Reading the NER degradation counter below for exactly what the counter does and does not prove.
• guardai_errors_total is a single unlabelled counter and carries no per-code breakdown, so use it only as the coarse "is anything failing" signal. For a specific code, query the structured application log or the audit stream: each failed request emits one request failed event carrying error_code, status, and request_id. A spike in error_code = GUARDAI_SESSION_EXPIRED may indicate TTL misconfiguration.
• Track guardai_rate_limit_rejections_total. Sustained rejections indicate capacity issues.
• Track guardai_output_guard_triggers_total. High trigger rate may indicate the LLM is generating PII or echoing raw session values instead of their tokens.

Reading the NER degradation counter

guardai_ner_degraded_total records a DETECTION outcome, not a request outcome. It is incremented once per protected operation whose detection produced regex-only coverage while the deployment has NER configured, which happens in two cases: the both-mode fallback when the sidecar is unreachable, and the benign case of a request that explicitly selects only builtin_regex. It is not a count of completed requests, and it is not disjoint from GUARDAI_DETECTION_UNAVAILABLE at request granularity.

What holds on every path: an advanced-mode outage, or an explicit python_ner selection that could not run, fails inside detection itself, before any path reaches the counter. So a GUARDAI_DETECTION_UNAVAILABLE (a sidecar outage) or GUARDAI_DETECTION_FAILED (a capability rejection) raised by the DETECTOR never coincides with an increment.

What does not hold globally is the counter implying a completed request. Each path places the increment at a different point relative to its remaining fail-closed steps:

Two consequences for alerting:

1. /v1/redact/image is the one path where a single request both increments the counter and returns GUARDAI_DETECTION_UNAVAILABLE. A both-mode sidecar outage under a policy whose detection.required_for names an NER-backed type increments first, then fails the policy check. Batch reaches the same result across items: one item increments while another reports GUARDAI_DETECTION_UNAVAILABLE in its per-item error.
2. On the structured, detect, RAG query, RAG context and batch paths the increment precedes later fail-closed steps, so the counter can move for a request that ends in GUARDAI_POLICY_DENIED, GUARDAI_AUDIT_UNAVAILABLE or GUARDAI_INTERNAL_ERROR.

Alert on the counter as "NER coverage was lost for this much traffic", not as "this many requests succeeded without NER". To attribute an outage, correlate it with the detector mode and the per-request error_code in the structured log rather than assuming the two signals partition the traffic.

Streaming (/v1/transform/stream) and file ingestion route through the transform pipeline, so they inherit whichever row above matches their input type. /v1/rehydrate and /v1/rag/answer run no detection and never touch the counter.