PII redaction 502 (fail-closed)

What you’ll see


{
  "error": "Upstream request failed",
  "detail": "Response could not be safely returned",
  "correlation_id": "...",
  "report_hint": { "url": "...", "suggested_payload": { /* ... */ } }
}

HTTP status 502. The upstream SaaS call may have succeeded — the problem is downstream of that, in the PII redaction stage.

In the dashboard’s Audit log, the corresponding row has:

result = "error"
metadata.reason = "pii_redaction_failed"
metadata.pii_error populated with the Presidio error kind (timeout, network, http, or breaker_open)
pii_redacted = false, pii_detected = null

Why

When your org has the PII Redaction beta flag enabled (toggled by superadmin under /superadmin), every successful upstream response is passed through the redaction layer before being returned to the agent: deterministic field-name and pattern matching always, plus an NLP analyzer + anonymizer (Microsoft Presidio) when one is deployed. The agent’s per-platform visibility map decides which entities are kept, masked, replaced, redacted, or hashed.

The NLP layer is not deployed in production today (retired 2026-07-22). Only the deterministic layers run, and they cannot fail closed. The timeout / network / http / breaker_open error kinds below can only occur on a deployment that has the NLP layer configured.

If Presidio errors — timeout, network failure, 5xx response, or the process-wide circuit breaker has opened after 5 consecutive failures — the proxy fails closed. The agent gets a generic 502 with no upstream body. No unredacted content leaks when redaction breaks.

This is by design. If redaction can’t be guaranteed, the only safe choice is to withhold the response.

Fix

Confirm the beta is intentionally on


Superadmin → Per-Org Beta Flags → search your org's owner email

If pii_redaction_enabled = false, the beta is off — and a 502 with this signature shouldn’t be possible. File a bug.

If on and you didn’t expect that, turn it off. The next call will skip Presidio entirely (zero added latency, no fail-closed path).

Check Presidio health

The proxy logs the Presidio error kind in metadata.pii_error:

Kind	Meaning	Fix
`timeout`	Analyzer took >2s or anonymizer took >1s	Only possible when the NLP layer is deployed (see the note above)
`network`	DNS / TCP / TLS failure reaching the redaction service	Only possible when the NLP layer is deployed; check `PRESIDIO_ANALYZER_URL` and `PRESIDIO_ANONYMIZER_URL` on the proxy
`http`	Presidio returned 4xx or 5xx	Check the Presidio container logs in Azure
`breaker_open`	5 consecutive Presidio failures opened the in-process breaker	The breaker auto-resets after 30 seconds. If it keeps opening, root-cause one of the kinds above

Confirm the agent’s claim makes sense

The fail-closed only fires when the agent has a per-platform visibility claim for the platform being called. If the agent has no claim, the proxy skips Presidio entirely and the response goes through unredacted (the “no claim” skip reason). Check Agent detail → PII Visibility to confirm the platform’s persona is what you expect.

Two circuit breakers, not one

There’s a separate circuit breaker for the agent itself (circuit_breaker_open) that auto-suspends an agent after 3 consecutive failures. PII-redaction failures count toward that breaker too. So a sustained Presidio outage will eventually suspend agents that hit it repeatedly.

The Presidio circuit breaker (in-process, process-wide, 5-failure threshold, 30-second cooldown) is a separate mechanism that protects the proxy from amplifying a Presidio outage by repeatedly hammering a dead service.