Skip to main content

How To: Investigate a Blocked Request

Use this workflow to find why Verdictan blocked a request.

Outcome​

At the end of this workflow, you know:

  • Which request ID and Event recorded the block.
  • Which policy or routing rule became decisive.
  • If the block agrees with policy intent.
  • If 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.
  • A related rollout, if applicable.

Each governed gateway response contains the correlation request ID. Preserve this ID in client logs and incident reports. Decision Events store correlation IDs as 32 lowercase hexadecimal characters. Verdictan stores a UUID without hyphens. Verdictan deterministically normalizes other text from the caller.

To use a correlation ID without conversion, send a 32-character lowercase hexadecimal X-Request-Id. If the reporter cannot give an ID, use the smallest available time window. Use the gateway, agent, model, and environment to find the Event.

Step 2: Find the Event​

Use an authenticated CLI profile that resolves to the selected region. The caller must have events:read permission.

Query recent blocked Events as JSON:

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

Use the matching Event request_id if it is available. If the response ID is a UUID, remove the hyphens before the comparison. If an ID is not available, make the time window smaller. Match the report against the gateway, agent, model, environment, and timestamp of the Event.

If no matching Event is delivered, first verify the gateway's control-plane connectivity. Verify the selected region and the request family's evidence support. An empty History view does not prove that the request did not occur.

Step 3: Examine the decisive evidence​

In the matching Event, examine:

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

This evidence shows if one strong control caused the result. It can also show an interaction between multiple rules.

Step 4: Add captured History context only when available​

History is not the source for all blocked requests. Use it only if the gateway history capture is enabled. The capture must include blocked requests. The session must also be available for the period that the platform retention policy allows. The capture mode controls if History contains full, redacted, or metadata-only context.

If one 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 configured history.capture behavior.

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

To learn if the behavior changed recently:

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

Step 6: Select the action​

Use this decision model:

  • Block agrees with policy: record the request identifier. Record which policy caused the behavior.
  • Unexpected but low-risk block: record the evidence. Then, propose a small policy adjustment.
  • Unexpected and high-impact block: contact the rollback owner. Verify the 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.
  • Last interpretation.
  • Links or export references when the issue must go to a different owner.

Next steps​