A Guard proxy answers blocked calls with an HTTP status and a JSON-RPC error body, so standard clients can parse it. A 403 with code -32000 means a policy rule denied the call. Other codes mean a blocked agent, a jailbreak score, a rate limit or a failing upstream. A bare 401 or 404 comes before policy.
The JSON-RPC errors
| HTTP | Code | Meaning | Check first |
|---|---|---|---|
| 400 | -32700 | Body is not valid JSON-RPC | The client's request format |
| 403 | -32000 | A policy rule denied the request | The message text, which includes the rule's deny reason |
| 403 | -32002 | The calling agent is blocked | The agent's status in the inventory |
| 403 | -32003 | The request or the response tripped the jailbreak threshold | The audit event scores |
| 429 | -32001 | A policy rule rate limited the request | The rule's rate limit |
| 502 | -32004 | The upstream MCP server errored or was unreachable | The server's health status |
An example denial body looks like this:
{
"jsonrpc": "2.0",
"id": 1,
"error": {
"code": -32000,
"message": "request denied by policy: destructive tool calls require monitor review"
}
}
Errors before policy
401. The request lacks a valid bearer key, or the key does not belong to the organization the server was registered under. Proxy keys begin with sg_live_ in production and sg_test_ in test environments.
404 with proxy URL not found. The slug never existed, or it was revoked. The proxy returns the same generic answer for both, so check the proxy URL record and spell the slug carefully.
Timing surprises
Slug resolution is cached for five minutes. A revoked slug can keep working for a short while. A brand new slug can take a moment to be picked up if it recently failed a lookup. If behavior changes do not appear at once, wait before assuming a bug.
Debugging steps
- Read the HTTP status and JSON-RPC code together. The table tells you the layer.
- For a 403, read the message. A deny reason usually names the rule.
- Find the event in the audit trail. See what the audit trail records. Allow up to about a second for it to appear.
- Check the rule order. See how Guard rules are evaluated.
- For a 502, test the upstream server directly, outside the proxy.
Do blocked calls reach the upstream?
No. A call the policy blocks never reaches the upstream server. It is still written to the audit trail, so a blocked call remains visible.
What the stream path does differently
The event stream path filters outputs such as personal data masking, but the full request time checks run on the message path. If your client uses both, the checks that matter run on the posted calls.
Show a clear message to users
Deny reasons are surfaced to the caller. Write them for the person who will read them, for example "Export tools need review. Ask the data team," not "rule 14 failed."
Quick check
Why do I get 404 for a slug I just revoked?
A revoked slug returns the generic not found. Resolution is cached for five minutes, so it may keep working briefly first.
Is a 502 a policy decision?
No. It means the upstream server errored or could not be reached.
Sources
Last reviewed: 19 October 2026.
