FAIRVISOR Docs
⌘K
GitHub fairvisor.com

Decision Tracing

Use this flow when debugging unexpected rejects.

Step 1: Capture reject headers

curl -i -X POST http://localhost:8080/v1/decision \
  -H 'X-Original-Method: POST' \
  -H 'X-Original-URI: /v1/chat/completions'

Collect:

  • X-Fairvisor-Reason
  • Retry-After
  • RateLimit-*

If you need policy/rule attribution, enable a debug session and inspect:

  • X-Fairvisor-Debug-Policy
  • X-Fairvisor-Debug-Rule

Step 2: Map reason -> limiter class

  • token_bucket_exceeded -> token_bucket
  • budget_exceeded -> cost_based
  • tpm_exceeded / tpd_exceeded -> token_bucket_llm
  • kill_switch -> kill switch pre-check
  • loop_detected / circuit_breaker_open -> advanced policy blocks

Step 3: Verify request context

In decision_service mode ensure gateway forwarded:

  • X-Original-Method
  • X-Original-URI
  • identity headers/JWT used in descriptors

Step 4: Check descriptor availability

If keys are missing, inspect:

rate(fairvisor_descriptor_missing_total[5m])

Step 5: Confirm policy/rule intent

  • Review selector match and method filters
  • Validate rule limit_keys, algorithm, and config
  • Validate fallback behavior and shadow mode

MD