Investigate a Blocked Request

When a request is blocked, the gateway records a decision event that says which policy or routing rule blocked it and why. This guide takes you from the error your application received to that event, and then to the right next action.

If a person must review the request instead, use Resolve an Escalation.

Before you start

Collect the approximate time, the gateway or agent, the region, and the X-Request-Id of the response, if you have it. Sign in with verdictan auth login with a role that has events:read.

1. Find the decision event

List the blocked decisions of the last 30 minutes, in the region of the gateway:

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

Add --region if the gateway is in another region, for example --region eu-west. Find the matching request_id in the events array.

Without a request ID, narrow the search with the --gateway-id filter, the timestamp, event_attribution.agent_id, and environment. If the response has next_cursor, run the command again with --cursor and that value.

Some errors happen before any decision is recorded. If no event matches, keep the original HTTP status and error body, and check the gateway connection and authentication.

The response ID and event ID have different formats

An event request_id is always 32 lowercase hexadecimal characters. A UUID loses its hyphens. Any other value becomes the first 32 characters of its SHA-256 digest.

This Python snippet does the same conversion. Replace the sample with your X-Request-Id:

import hashlib
import uuid

request_id = "docs-block-check-01".strip()
try:
    event_request_id = uuid.UUID(request_id).hex
except ValueError:
    event_request_id = hashlib.sha256(request_id.encode()).hexdigest()[:32]
print(event_request_id)

For a new test, send an X-Request-Id that is already 32 lowercase hexadecimal characters, so nothing changes. The events API can filter by request_id. The CLI tail command cannot.

2. Find the cause of the block

Note these fields from the matching event:

Field	Tells you
request_id, event_id	How to find the same request again
verdict, reason_code	The result and its reason
details	The policy results and redaction markers
config_id, config_version	The configuration that decided
Provider, model, time, gateway, and agent	That this is the request you were told about

Then compare the result with what the policy is meant to do. A correct block and a wrong block need different next steps.

3. Add context if necessary

History shows the retained prompt and response. Blocked requests appear there only when capture is on and history.capture.include_blocked is true, which is not the default. Capture mode and retention limit what is kept. A missing History session does not make the decision event wrong. See Runtime Configuration.

If the behavior changed after a rollout, compare config_version with Configurations, and use Trail to find who changed the configuration and when. If the request also created a review item, look in Inbox.

4. Select the next action

Finding	Next action
The policy blocked the request correctly	Tell the application owner the reason, and keep the request ID.
The policy needs a small change	Add a test for this request, then follow Managing Policy Changes.
A rollout caused the failures	Contact the rollback owner and check the applied configuration in Gateways.
The evidence is not conclusive	Write down what is missing and hand it to the responsible reviewer.

Verify your conclusion

Someone else must be able to find the same event from your notes: the request ID, region, time, configuration version, reason, and next action.

Never change a policy only to make an error go away. Test the intended allow and block behavior before a rollout.

If you cannot find the evidence

Problem	What to check
No events found.	Region, profile, gateway, time window, and event delivery
Authentication fails	Sign in again with an account that has events:read.
The IDs do not match	Convert the response ID as shown above.
No History session	Capture settings, include_blocked, request family support, and retention

Next steps

• verdictan events: filter and export decision events.
• Export Evidence for a Review: download a time range.
• Resolve an Escalation: record a human decision.