Skip to main content

How To: Investigate a Blocked Request

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

Outcome​

By the end of this workflow, you should know:

  • Which request ID and Event recorded the block.
  • Which policy or routing rule 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.
  • The gateway response's X-Request-Id value, if available.
  • Whether this behavior started after a rollout.

Every governed gateway response carries the correlation request ID. Preserve it in client logs and incident reports. Decision Events store correlation IDs as 32 lowercase hexadecimal characters: a UUID is stored without hyphens, while other caller-supplied text is deterministically normalized. For exact correlation without conversion, have the client send a 32-character lowercase-hex X-Request-Id. If the reporter cannot provide an ID, use the smallest available time window plus the gateway, agent, model, and environment to locate the Event.

Step 2: Find the Event​

Use an authenticated CLI profile that resolves to the affected region. The caller needs events:read permission.

Query recent blocked Events and request JSON so the request IDs and full event fields remain visible:

kt events tail --since 30m --event-type decision --verdict blocked --json

Find the exact Event request_id when you have it. If the response ID is a UUID, compare it after removing the hyphens. If the caller sent an arbitrary text ID or no ID was retained, narrow the time window and use the Event's gateway, agent, model, environment, and timestamp to match the report.

If no matching Event arrives, first verify the gateway's control-plane connectivity, the selected region, and the request family's evidence support. Do not treat an empty History view as proof that the request did not occur.

Step 3: Inspect the decisive evidence​

In the matching Event, focus on:

  • request_id, final verdict, and reason_code.
  • Policy results and any redaction marker in the delivered details.
  • Provider and model information.
  • Timestamps and latency context.
  • config_version, environment, gateway, and agent attribution.

This tells you whether the result came from a single strong control or a broader rule interaction.

Step 4: Add captured History context only when available​

History is not the universal source for blocked requests. Use it only when the gateway's history capture is enabled, blocked-request capture is included, and the relevant session remains available under the platform's retention policy. The capture mode determines whether History contains full, redacted, or metadata-only context.

If any of those conditions is false, continue the investigation with the request ID and Event. A missing History session is not evidence that the Event or block is invalid. See Runtime Configuration for the exact history.capture behavior.

Step 5: Correlate with rollout or audit context if needed​

If you need to understand whether the behavior changed recently:

  • Compare with the version history in Configurations.
  • Open Trail if you need audit chronology or exportable evidence.
  • Open Inbox if the same workflow also created a human-review item.

Step 6: Decide the operational outcome​

Use this decision model:

  • Expected block: capture the request identifier 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 and the deployment workflow.
  • Ambiguous case: move into a human-review workflow with a clear owner.

Evidence checklist​

Before closing the investigation, preserve:

  • Response request ID, normalized Event request ID, and Event ID.
  • Time window.
  • Configuration version.
  • Final interpretation.
  • Links or export references when the issue needs handoff.

Next steps​