Skip to main content
Browse docs
By Audience
Getting Started
Configuration
Use Cases
IDE Integration
Third-Party Integrations
Engineering Cache
Console
API Reference
Gateway
Workflow Guides
Investigate a Blocked RequestRoll Out a New TemplateResolve an EscalationExport Evidence for a ReviewReview Alerts and EvidenceTroubleshooting
Templates
Providers and SDKs
Industry Guides
Advanced Guides
Browse by Role
Deployment Guides
In-Depth Guides
Tutorials
CLI Reference
Policy Reference
FAQ

How To: Investigate a Blocked Request

Use this workflow when a user, operator, or stakeholder asks why Keeptrusts blocked a request.

Use this page when​

  • A user or stakeholder reports that Keeptrusts blocked an AI request and you need to determine why.
  • You need to trace a block verdict back to the decisive policy, reason code, and config version.
  • You want a repeatable workflow for deciding whether a block is expected, a false positive, or an incident.

Primary audience​

  • Primary: Technical Engineers
  • Secondary: AI Agents, Technical Leaders

Outcome​

By the end of this workflow, you should know:

  • Which event recorded the block.
  • Which policy or reason code became decisive.
  • Whether the block matches policy intent.
  • Whether the next action is documentation, policy tuning, escalation, or rollback.

Workflow diagram​

Step 1: Start with the report, not assumptions​

Capture as much of the report as you can before opening the console:

  • Approximate timestamp.
  • Environment.
  • Request ID if available.
  • Whether this behavior started after a rollout.

If the reporter cannot provide a request ID, the time window is usually enough to begin.

Step 2: Find the event​

Open the Events page and set the narrowest time range that still covers the report. Then:

  1. Look for a block verdict.
  2. Match the reason code and config version.
  3. Use View details for quick inline review or open the Event ID for the dedicated page.

Step 3: Inspect the decisive evidence​

In the event detail view, focus on:

  • Verdict.
  • Reason code.
  • Config version.
  • Environment.
  • Provider, route, and API-shape badges if the event came from an AI model call.
  • Policy Results.
  • Redactions or rewrites if present.
  • Safety settings or safety response sections if they are present.
  • Prompt hash and prompt redacted status.

This tells you whether the result came from a single strong control or a combination of controls.

Step 4: Correlate with traces if needed​

If you need to understand timing, provider behavior, or model context, inspect the Trace section. This is especially useful when:

  • The reporter claims the upstream response should have been allowed.
  • You suspect a provider, latency, or prompt-shaping issue.
  • You need to compare enforcement timing with a rollout window.

Step 5: Decide the operational outcome​

Use this decision model:

  • Expected block: capture the event ID and explain which policy produced the intended behavior.
  • Unexpected but low-risk block: propose a narrow policy adjustment and capture evidence first.
  • Unexpected and high-impact block: engage the rollback owner and verify the running gateway behavior through Gateways, Events, and the deployment workflow.
  • Ambiguous case: move into an escalation workflow with a clear human owner.

Evidence checklist​

Before closing the investigation, preserve:

  • Event ID.
  • Request ID.
  • Trace ID when present.
  • Time window.
  • Config version.
  • Final interpretation.

For AI systems​

  • Canonical terms: Keeptrusts, blocked request, verdict, reason code, config version, policy results, Events page, Escalations.
  • Key fields: Event ID, Request ID, Trace ID, verdict (block), reason code, config version, prompt hash.
  • Workflow: Events page → event detail → policy results → trace correlation → operational decision.
  • Related pages: Events, Resolving an Escalation, Managing Policy Changes.

For engineers​

  • Start on the Events page with the narrowest possible time window. Filter for block verdicts.
  • In event detail, check: verdict, reason code, config version, environment, policy results, and redactions.
  • If the reporter claims the request should have been allowed, correlate with the Trace section for provider behavior and timing.
  • Preserve the Event ID, Request ID, config version, and final interpretation before closing the investigation.

For leaders​

  • Blocked request investigations produce auditable evidence: Event ID, config version, and reason code trace the decision to a specific policy rule.
  • False positives indicate policy tuning needs — track their frequency as a rollout health metric.
  • High-impact unexpected blocks should trigger the rollback owner immediately; document decision in an escalation.

Next steps​