Response Headers

Header presence depends on decision path and limiter result. Not every response contains all headers.

Rate-limit headers

Header	Present when	Notes
`RateLimit-Limit`	Limiter returns `limit`	Algorithm-dependent
`RateLimit-Remaining`	Limiter returns `remaining`	Algorithm-dependent
`RateLimit-Reset`	Limiter returns `reset` or `retry_after`	Fallback `1` in some limiter paths
`RateLimit`	A limiter result exists	Structured: `"<policy_or_rule>";r=<remaining>;t=<reset>`

Fairvisor follows the standard RateLimit* header model from:

Reject headers

Header	Present when
`Retry-After`	Reject decisions

Retry-After includes deterministic per-identity jitter and is not runtime-configurable.

X-Fairvisor-Policy, X-Fairvisor-Rule, and the reject reason are emitted in debug-session headers only (as X-Fairvisor-Debug-Policy, X-Fairvisor-Debug-Rule, X-Fairvisor-Debug-Reason). See Debug Session.

Advisory headers

Header	Present when
`X-Fairvisor-Warning`	Non-blocking warning paths (`budget_warn`, `budget_throttle`, `loop_warn`)
`X-Fairvisor-Loop-Count`	Loop detector emits loop metadata

Debug headers

Debug headers are available only on requests that carry a valid signed debug cookie. Set FAIRVISOR_DEBUG_SESSION_SECRET and call POST /v1/debug/session to obtain one.

Header	Notes
`X-Fairvisor-Decision`	Effective decision action
`X-Fairvisor-Mode`	`enforce` or `shadow`
`X-Fairvisor-Latency-Us`	Decision latency in microseconds
`X-Fairvisor-Debug-Decision`	Same as above (verbose form)
`X-Fairvisor-Debug-Mode`	Same as above (verbose form)
`X-Fairvisor-Debug-Reason`	Internal reject reason
`X-Fairvisor-Debug-Policy`	Policy ID that triggered the decision
`X-Fairvisor-Debug-Rule`	Rule name that triggered the decision
`X-Fairvisor-Debug-Latency-Us`	Same as above (verbose form)
`X-Fairvisor-Debug-Matched-Policies`	Number of policies evaluated
`X-Fairvisor-Debug-Descriptor-*`	Per-descriptor key/value pairs (up to 16)

See Debug Session.

Notes on token headers

Some docs/examples may show additional token-specific headers such as X-Fairvisor-TPD-Remaining. Treat those as implementation-dependent unless explicitly documented by your running version.

Shadow mode

In shadow mode, would-reject decisions are converted to allow. Reject-specific response headers are suppressed for the client path.

Top-level runtime overrides (global_shadow, kill_switch_override) also do not add client-visible response headers. Use logs and metrics to verify override state.

`decision_service` vs `reverse_proxy`

In decision_service, headers are returned on /v1/decision and must be forwarded by the gateway.
In reverse_proxy, headers are attached on proxied responses in nginx filter phases.