AgentTrust Docs

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.

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`
402	Payment Required — tier does not include this feature	Upgrade tier; the message names the required tier
403	Forbidden — authenticated but not permitted (RBAC)	Check the caller's role
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`	Only `parent_envelope_id` without `trust_chain`, and only with `raise_on_tier_gate=True`. Adapters raise plain `RuntimeError` instead.

from agentrust_sdk import (
    BlockedError,
    TierGateError,
    GatewayUnavailableError,
    GatewayVersionError,
)

All four are re-exported at package level. BlockedError also lives in agentrust_sdk.decorator; the gateway errors live in agentrust_sdk.client. Import from the top-level package and you never have to remember which.

TypeScript errors

import {
  AgentTrustError,          // base class for all of the below
  BlockedError,
  GatewayUnavailableError,
  TierGateError,
} from 'agentrust-sdk';

There is no GatewayError export — the gateway failure class is GatewayUnavailableError, and the TypeScript SDK has no GatewayVersionError (a 426 response surfaces as a plain Error).

Examples

Handle all SDK errors:

import os

from agentrust_sdk import (
    AgentTrustClient, BlockedError, GatewayUnavailableError, TierGateError,
)

os.environ["AGENTRUST_FAILURE_MODE"] = "closed"   # env-only; no constructor arg

try:
    with AgentTrustClient() as client:
        result = client.validate(
            agent_id="my-agent", user="alice",
            input="…", output={"ok": True},
        )
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)

Best Practices

Alert on GatewayUnavailableError in production with failure_mode=closed
Log BlockedError.reason and BlockedError.envelope_id with every block
Handle 429 with exponential backoff
Never swallow 402 — it means the feature is not in your tier, not that the request was malformed

Common Mistakes

Catching generic Exception and continuing (masks governance failures)
Not distinguishing gateway down (503) from block (200 with block outcome)

Troubleshooting

See Troubleshooting.

API Errors