AgentTrust Docs

Open in ChatGPT

Overview

Reference for HTTP error codes returned by the AgentTrust gateway and SDK exceptions raised on the client side.

Why It Matters

Correct error handling prevents silent governance bypass and enables proper alerting.

Prerequisites

None — reference document.

Step-by-Step Guide

Gateway HTTP errors

Status	Meaning	Action
400	Bad request — malformed body	Fix request schema
401	Unauthorized — missing/invalid token	Check `AGENTRUST_KEY`
403	Forbidden — tier insufficient	Upgrade tier
404	Resource not found	Verify envelope_id
422	Unprocessable — validation failed	Fix request fields
429	Rate limited	Back off; increase limit in config
500	Internal error	Check gateway logs
503	Service unavailable	Check Postgres/Redis health

SDK exceptions

Exception	When raised
`BlockedError`	Decision outcome is `block` (or escalate with block config)
`GatewayUnavailableError`	Gateway unreachable + `failure_mode=closed`
`GatewayVersionError`	SDK/gateway version incompatible
`TierGateError`	Tier-gated adapter or capability blocked

from agentrust_sdk import BlockedError, TierGateError, GatewayUnavailableError
from agentrust_sdk.decorator import BlockedError  # same class

TypeScript errors

import { BlockedError, GatewayError } from 'agentrust-sdk';

Examples

Handle all SDK errors:

from agentrust_sdk import AgentTrustClient, BlockedError, GatewayUnavailableError, TierGateError

try:
    with AgentTrustClient(failure_mode="closed") as client:
        result = client.validate(...)
except BlockedError as e:
    log.warning("Governance blocked: %s", e)
except GatewayUnavailableError:
    alert_ops("AgentTrust gateway down")
except TierGateError as e:
    log.error("Upgrade required: %s", e)