| description | Typed exceptions for every governance refusal, each with a discriminator, a retry rule, and a next step. |
|---|---|
| status | live |
import { Callout } from 'nextra/components'
The proxy doesn't just pass model calls through — it enforces policy. When it rejects a call, DDK turns the response into a typed exception so you branch on the governance outcome instead of parsing bodies.
classify() types ten rejection shapes. Neither the status code nor the
shape of the error value alone is a sufficient discriminator — a 403 can be
PII, a killed agent, a regex-guard block, a content-safety block (all policy
blocks) or auth,
and the same nested-object envelope is emitted by both the upstream provider and
a gateway policy. The authoritative discriminator is the error type plus
specific headers.
| Rejection | HTTP | Discriminator | Maps to |
|---|---|---|---|
| Client-ID enforcement (auth) | 401 |
flat {"error":"…"} + www-authenticate: Client-ID-Enforcement |
AuthError |
| PII detected | 403 |
nested {"error":{type:"pii_detected"}}, no www-authenticate |
PIIDetected (parses entities) |
| Agent kill switch | 403 |
nested {"error":{code:"agent_killed"}}, no type, no www-authenticate |
AgentKilled |
| Injection protection | 400 |
header x-injection-protection: blocked (not the status) |
PromptInjectionBlocked |
| Regex prompt guard | 403 |
top-level matched_patterns list (flat error) |
PromptInjectionBlocked (policy="regex-prompt-guard") |
| Content safety / guardrails | 403 |
header x-llm-proxy-<vendor>-…-action: reject (Azure Content Safety / Bedrock Guardrails / Google Model Armor / CrowdStrike AIDR). The CrowdStrike AIDR shape is read from the policy's source, not captured from a live gateway. The same header on a 503 is the policy failing closed (its moderation service was unreachable): an UpstreamModelError |
ContentSafetyBlocked (sets provider, parses categories) |
| Token rate limit | 429 |
empty body; x-token-limit/-remaining/-reset headers (ms) |
TokenBudgetExceeded (retry_after derived) |
| Request rate limit | 429 |
body {"error":"Too Many Requests"}; x-ratelimit-limit/-remaining/-reset headers (ms), no x-token-*, no retry-after |
RequestRateLimitExceeded (retry_after derived) |
| Content moderation (undiscriminated) | 4xx |
falls through — no nested error, no injection/guard/safety discriminator |
generic PolicyViolation |
| Upstream provider 4xx | 4xx |
nested error object with code/type/param — in an OpenAI-style object envelope {"error":{…}} or a Gemini-style list envelope [{"error":{…}}] (status→error_type) |
UpstreamRequestError |
| Upstream 5xx | 5xx |
status range (no competing discriminator) | UpstreamModelError (retryable) |
| Bare model name on a multi-provider proxy | 400 |
flat {"error":"…"} saying the model "is not in the known unique model map" |
ModelNotRoutable (.model) |
| No model where the ingress expects one | 400 |
flat {"error":"…"} saying "Missing 'model' field in request" (no model body field, or an OpenAI body sent to a native Gemini ingress) |
ModelNotRoutable (.model is None) |
| Provider with no route and no fallback | 400 |
flat {"error":"…"} saying "Unsupported provider '…'. No fallback configuration." (a provider/model whose provider the proxy does not route) |
ModelNotRoutable (.provider) |
| OAuth2 OBO step-up (CIBA), waiting for the user | 401 |
flat {"error":"authorization_pending"} + retry-after, no www-authenticate |
GatewayApprovalPending (retry_after) |
| OAuth2 OBO step-up (CIBA), user denied | 403 |
flat {"error":"access_denied"}, no www-authenticate |
GatewayApprovalDenied (policy="oauth2-obo-ciba") |
PIIDetected, AgentKilled, the regex-prompt-guard check, and the content-safety
check are all evaluated before the generic 401/403→auth rule, because each is
a 403 (or 4xx) that is not an auth failure. AgentKilled is also checked
before the upstream-4xx rule: its nested error object would otherwise read as
an upstream request mistake, when the upstream was never called. Likewise the injection check gates on the
x-injection-protection header, so an ordinary malformed 400 stays an
ordinary refusal. The two CIBA step-up answers are checked before the auth rule
too: the gateway accepted the credential and is asking the user to approve the
call on another device, so an AuthError would point you at the wrong fix.
For ordinary HTTP envelopes, classify() checks the policy discriminators first, whatever the status, and
only then falls back to the status code. Within each step the first match wins,
top to bottom:
flowchart TD
R(["Error response"]) --> D{"1 · Policy discriminator<br/>in the body or headers?"}
D -->|"nested error type = pii_detected"| X1["PIIDetected"]
D -->|"nested error code = agent_killed"| X2["AgentKilled"]
D -->|"x-llm-proxy-*-action: reject"| X3["ContentSafetyBlocked"]
D -->|"top-level matched_patterns"| X4["PromptInjectionBlocked<br/>regex-prompt-guard"]
D -->|"x-injection-protection: blocked"| X5["PromptInjectionBlocked"]
D -->|"401 + flat error = authorization_pending"| X14["GatewayApprovalPending"]
D -->|"403 + flat error = access_denied"| X15["GatewayApprovalDenied"]
D -->|none| S{"2 · Status"}
S -->|"401, or 403 + www-authenticate"| X6["AuthError"]
S -->|429| Q{"x-ratelimit-limit and -remaining,<br/>no x-token-limit?"}
Q -->|yes| X7["RequestRateLimitExceeded"]
Q -->|no| X8["TokenBudgetExceeded"]
S -->|"other 4xx"| F{"Body"}
F -->|"nested error object"| X9["UpstreamRequestError"]
F -->|"flat error: not in the<br/>known unique model map,<br/>missing 'model' field,<br/>or unsupported provider"| X10["ModelNotRoutable"]
F -->|anything else| X11["PolicyViolation<br/>unconfirmed shape"]
S -->|5xx| X12["UpstreamModelError<br/>retryable"]
S -->|"anything else"| X13["DonkeyError"]
GatewayUnavailable never reaches classify(): it is raised when there is no
response to classify.
A gateway policy of your own, such as a PDK policy, sends a shape none of these
rules know, so it lands on one of the "other 4xx" rows. Register the shape with
classify.register() to type it as an exception you define. A registered shape
is checked after every built-in policy rule and before the UpstreamRequestError
and unconfirmed-PolicyViolation rows, so a built-in shape always wins. See
Custom policies.
RequestRateLimitExceeded is the 429 of the gateway's stock rate-limiting
policy, which counts requests rather than tokens. It is a subclass of
PolicyViolation and a sibling of TokenBudgetExceeded, not a subclass of it.
A 429 carrying x-ratelimit-limit and x-ratelimit-remaining and no
x-token-limit is a RequestRateLimitExceeded; any other 429 stays
TokenBudgetExceeded. The headers appear only when the policy has
exposeHeaders: true, the only configuration verified. With
exposeHeaders: false there is nothing to key on: that shape is UNVERIFIED
and is classified as TokenBudgetExceeded. retry_after comes from
retry-after if present, else from x-ratelimit-reset (milliseconds). The
upstream provider's suffixed x-ratelimit-limit-requests / -tokens headers are
a different window: they fill donkey.budget.upstream and play no part in
classification.
Client-ID enforcement (401) is a consumer-auth case, not one of the ten
policy-rejection rows.
The CIBA step-up rows come from the OAuth2 OBO Credential Injection policy with
cibaEnabled. While the user hasn't answered, every call gets a 401
authorization_pending with a retry-after (the policy's poll interval plus
two seconds); once they approve, the same request succeeds. A request nobody
answers is never reported as expired: the policy starts a new approval flow and
keeps answering "pending", so keep your own deadline. After a deny, the gateway
caches the decision; on OBO policy 1.1.3 it does so per user, not per
conversation, for up to an hour. The policy's initiation failure (502,
ciba_initiation_failed) has no type of its own and is an
UpstreamModelError, like any other 5xx.
The SDK does not retry a pending approval on its own. To wait for one while listing an
MCP server's tools, use toolset.wait_for_gateway_approval("2m"): it re-sends the
tools/list after each retry_after until the user approves, raises
GatewayApprovalDenied at once if they deny, and raises the last
GatewayApprovalPending when the timeout passes. A tool call is never retried, and
whether its answer is typed depends on the installed mcp package. On mcp 1.x, a tool
from a per-tool binding, or any call under donkey.run() or typed_refusals(), raises
GatewayApprovalPending, GatewayApprovalDenied or, for the kill switch, AgentKilled.
On mcp 2.x the client raises an MCPError -32603 with no status or body, so the
answer reaches you as the framework's own error. Step-up on a tool
call has the details. donkey mock --scenario ciba:pending=2 plays the sequence offline. Gateway step-up
covers the whole flow.
The Injection Protection shape is live-verified against a deployed proxy
(#669); classify() keys on the header discriminator alone for it, not the
body.
from donkey_kit import jsonrpc_refusal provides a
framework-free matcher for raw error mappings, full envelopes or exceptions
with .error, including causes, contexts and exception groups. It returns a
policy refusal or None when the error is ordinary or ambiguous (BG §2.2).
The existing -32008 / "Unable to access" pair remains ToolNotInProfile.
MCP PII rejections with data.policy="mcp-pii-detector" and
data.reason="policy_pii_detected" become PIIDetected when the phase/code
pair is request / -32602 or response / -32603. Both markers and the
pair are required; the code or diagnostic text alone never identifies PII.
Other explicit data.policy or policy_* reason markers without a matching custom
registration become PolicyViolation(policy="unknown"), not a guessed PII or
schema type. Generic codes, diagnostic strings and A2A ErrorInfo reasons such
as FORBIDDEN / INVALID_PARAMS do not identify a policy. See
JSON-RPC custom registrations.
For the captured A2A Azure guardrail refusal, HTTP 403 with
x-flex-azure-guardrails-action: reject yields
ContentSafetyBlocked(provider="azure-content-safety"). Its .categories
come from x-flex-azure-guardrails-reason; both classify(response) and
jsonrpc_refusal(error, status=403, headers=response.headers) recognise it.
The RPC helper requires HTTP status and headers for this rule; it does not
guess them from the error body. A token-policy HTTP 429 with x-token-*
headers is TokenBudgetExceeded, with the reset converted from milliseconds
to seconds. Use classify(response) for that HTTP-only rate-limit path.
A2A PII and schema-policy responses still lack a reliable policy identifier:
classify(response) returns a safe ToolInvocationError, and
jsonrpc_refusal(...) returns None. Neither diagnostic text nor missing
guardrail headers identifies PII. Fail-closed Azure and Bedrock HTTP 503
responses remain UpstreamModelError, not ContentSafetyBlocked or
GatewayUnavailable. A Bedrock A2A content-block shape remains unverified.
See A2A gateway policies for the version-specific
capture inventory and the difference between refusals and auth-required tasks.
When you explicitly call classify(response) on a jsonrpc: "2.0" error
envelope, genuine HTTP 401/auth challenges and 429 win. Other ordinary/ambiguous
JSON-RPC failures become a safe ToolInvocationError, without repeating raw
error.message/data. The original response stays on .response; handle it as
potentially sensitive. The legacy access denial still parses only its tool name.
Existing HTTP/header built-in discriminators still win, but their RPC rendering
does not derive labels from raw RPC diagnostics. For example, PIIDetected
from an RPC envelope has no message-derived entities or gateway_message;
the raw bytes remain only on the original .response. Auth challenges on
explicitly classified HTTP 200/400 envelopes are auth errors too; 429 retains
rate-limit precedence.
Normal HTTP classification is unchanged. MCP binding coverage and A2A
PII/schema-specific typing are unchanged. The scoped outbound A2A
facade now intercepts non-success HTTP responses and buffered
JSON-RPC errors, including HTTP 200 error envelopes, before SDK rendering.
Successful streams remain unread by core; the official SDK handles their
protocol events. SDK parsing/protocol failures become safe ToolInvocationError.
Original HTTP responses on errors remain potentially sensitive; do not log them.
The MCP gateway policy inventory covers policy configuration boundaries and which native bindings preserve these refusals.
For an MCP PII rejection, .policy is "mcp-pii-detector", .phase is
"request" or "response", and .findings is a safe projection with only
pii_type and masked_value. Types are canonical SSN, Email, CreditCard,
PhoneNumber or Custom; custom pattern labels are discarded. Every character
of the gateway's masked value is replaced with *, capped at 256 characters:
even a partially masked email domain is withheld. Unknown or malformed findings
are omitted, without losing the typed refusal when its discriminators match.
.entities derives from these projected types and .gateway_message is None.
The original .response remains raw and potentially sensitive; do not log it.
The existing LLM PII contract is unchanged: .entities and .gateway_message
retain their behavior, with additive defaults .phase=None and .findings=[].
MCP HTTP 403 PII refusals are terminal and never automatically retried. An HTTP
200 JSON-RPC error is recognized only when you explicitly call classify() or
jsonrpc_refusal(); successful transport responses are not intercepted.
The captured response-phase rejection on an SSE upstream is HTTP 403 JSON, not an SSE error event. SSE error-event handling and elicitation decline are not established by this matcher. The binding refusal coverage is local capture replay, not new live framework calls to the gateway.
All importable from donkey_kit, along with classify, except the Roadmap-surface errors on the last line, which are in donkey_kit.experimental:
DonkeyError # base of the whole tree
├─ ConfigError # misconfiguration or client misuse (raised locally, no request sent)
├─ AuthError # rejected data-plane credentials or control-plane auth
├─ PolicyViolation # base for every governance rejection
│ ├─ PIIDetected # LLM type=pii_detected or MCP PII markers; .entities, .phase, .findings
│ ├─ AgentKilled # 403, code=agent_killed — the Agent Kill Switch blocked this agent
│ ├─ GatewayApprovalDenied # 403, error=access_denied — the user denied the CIBA step-up; also an ApprovalError
│ ├─ TokenBudgetExceeded # 429; .retry_after (seconds)
│ ├─ RequestRateLimitExceeded # 429, rate-limiting policy; .retry_after (seconds); sibling of TokenBudgetExceeded
│ ├─ PromptInjectionBlocked # x-injection-protection: blocked, or regex matched_patterns
│ ├─ ContentSafetyBlocked # Azure Content Safety / Bedrock Guardrails / Google Model Armor / CrowdStrike AIDR (policy source) 403 reject header; .provider, .categories
│ └─ ToolNotInProfile # MCP tools/call refused: JSON-RPC -32008 "Unable to access"; .tool_name, .server
├─ GatewayApprovalPending # 401, error=authorization_pending — waiting for the user's CIBA approval; .retry_after
├─ GatewayAuthRequired # captured v0.3 auth-required task; .challenge and returned .task_id/.context_id
├─ GatewayUnavailable # transport failure — gateway unreachable, NO response; .base_url/.cause (ungoverned)
├─ UpstreamRequestError # upstream 4xx; .code/.error_type/.param
├─ ModelNotRoutable # 400, bare model name on a multi-provider proxy, no model, or an unrouted provider; .model/.provider
├─ UpstreamModelError # upstream 5xx — provider error, retryable
├─ BudgetReserveReached # client-side, from budget.pace(); .fraction_used/.reserve/.reset_at/.window
├─ ModelSubstituted # client-side, opt-in; .requested_model/.served_model/.served_provider
├─ ApprovalRequired # client-side: an approval-gated tool was called, not run; .approval
├─ ApprovalError # an approval was refused, so the call did not happen
│ ├─ ApprovalRejected # client-side: a reviewer refused a framework-paused tool; .approval
│ └─ GatewayApprovalDenied # (also under PolicyViolation, above)
├─ ApprovalTimedOut # client-side: nobody decided before approval_timeout; .approval
├─ ApprovalNotFound # client-side, also a KeyError: no such pending approval on this Donkey; .approval_id
├─ UngovernedMcpServer # client-side: a ToolSet binding refused an ungoverned server; .servers, .reasons
└─ ToolInvocationError, RegistryError, PublicationDrift, DescriptorMismatch
# tool calls, registry and publishing (Roadmap surfaces;
# import them from donkey_kit.experimental)
GatewayUnavailable is deliberately not under PolicyViolation: it is the one
ungoverned failure in the tree (see below). Everything under PolicyViolation is
something the gateway told the SDK; GatewayUnavailable is the gateway not being
there to tell it anything.
One row per exception you can catch, with the three facts you need to write a
handler: what tells it apart (the discriminator), whether retrying it can
ever succeed, and the next step its .remediation names. "Retryable" here
means by you — the transport already retries the only class that is safe to
(UpstreamModelError), and treats every governance refusal as terminal so it can
never burn an exhausted budget or replay a blocked prompt.
| Exception | Discriminator | Retryable? | Next step (.remediation) |
|---|---|---|---|
AuthError |
Data plane: 401, or 403 + www-authenticate. Control plane: Anypoint auth-provider or connected-app token acquisition fails, or a registry read is refused (401/403) because the connected app lacks a scope. Inside donkey.as_user(): a missing token — never a fallback to the service identity. An approved tool resumed inside as_user() with a token other than its requester's: the tool is not run. A per-tool MCP binding called under a different user from the one it was bound for: the call is not sent. |
No — terminal. In jwt mode the async data-plane client refreshes the wallet JWT and retries once on a 401, then surfaces it; in client-id mode a data-plane 401 surfaces immediately. Control-plane token acquisition surfaces immediately and never affects model calls. |
Data plane: check the consumer client_id / client_secret pair and API Manager authorization. Control plane: check the configured auth provider; for a connected app, verify ANYPOINT_CLIENT_ID / ANYPOINT_CLIENT_SECRET and the required scopes. A refused registry read names the missing scope; see Connected-app scopes. as_user(): pass the signed-in user's current token. A refused resume: resume outside as_user(), so the tool runs as its requester. A refused MCP tool call: bind the ToolSet inside the as_user() block that runs the agent. |
PIIDetected |
LLM: 403, nested type: "pii_detected", no www-authenticate. MCP: both PII markers and phase/code pair described above. |
No — a PolicyViolation, never retried. |
Remove or redact the flagged values (.entities), or relax the policy's entity list in API Manager. |
AgentKilled |
403, nested code: "agent_killed", no type |
No — a PolicyViolation, never retried; the agent stays blocked until an administrator restores it. It also stops donkey.budget.pace() loops, and spans are flushed before it reaches you. |
Ask an administrator to restore this agent's model access in Governance > Security. |
GatewayApprovalPending |
401, flat error: "authorization_pending", no www-authenticate |
Yes, after .retry_after — never auto-retried; the same request succeeds once the user approves. |
Re-send after .retry_after seconds; don't change or refresh the credentials, they were accepted. |
GatewayApprovalDenied |
403, flat error: "access_denied" |
No — a PolicyViolation, never retried; the gateway keeps answering with the denial until its cached decision expires. |
Tell the user the action was not authorized. |
GatewayAuthRequired |
Complete captured v0.3 auth-required task with status-message authChallenge, decoded by the outbound facade |
No automatic replay; not a policy refusal or CIBA polling outcome. | Validate the challenge metadata and hand it to your application's OAuth flow. DDK does not acquire tokens or resend the task; completed OAuth is unverified. |
TokenBudgetExceeded |
429, empty body, x-token-* headers |
Not immediately — never auto-retried; only worth retrying after the window resets. | Wait for .retry_after (seconds) / the reset, then retry — or request an increase in API Manager. |
RequestRateLimitExceeded |
429 with x-ratelimit-limit and x-ratelimit-remaining and no x-token-limit |
Not immediately — never auto-retried; only worth retrying after the window resets. | Wait for .retry_after (seconds) / the reset, then retry — or request an increase in API Manager. |
PromptInjectionBlocked |
header x-injection-protection: blocked, or a top-level matched_patterns list (regex prompt guard) |
No — a PolicyViolation, never retried. |
Review and sanitise the untrusted input, or adjust the policy's sensitivity / deny-list in API Manager. |
ContentSafetyBlocked |
403 + x-llm-proxy-<vendor>-…-action: reject (Azure Content Safety / Bedrock Guardrails / Google Model Armor / CrowdStrike AIDR, whose shape is read from the policy's source and not captured live) |
No — a PolicyViolation, never retried. |
Revise the flagged content (.categories), or adjust the policy's categories / severity thresholds in API Manager (for Google Model Armor, the template's filters in Google Cloud; for CrowdStrike AIDR, the collector's AIDR policy in the Falcon console). |
ToolNotInProfile |
An MCP tools/call answered with HTTP 200 and the JSON-RPC error -32008 "Unable to access" (the gateway's MCP Global Access or Attribute-Based Access Control policy). The LangGraph, LlamaIndex and Anthropic ToolSet bindings raise it; tool_access_denial(exc), jsonrpc_refusal(exc) or an explicit classify(response) can convert it elsewhere. The transport does not automatically inspect successful 200 bodies. See Tools outside your access profile. |
No — a PolicyViolation, never retried; a configuration problem that no retry or rephrasing fixes. |
Ask the server's owner to grant the tool (.tool_name) in the MCP access policy on its API instance in API Manager, or stop offering it to the agent. |
PolicyViolation (generic) |
a 4xx matching no known rejection shape |
No — terminal. | Inspect .response; file an issue with the status/headers/body so the shape can be typed. |
UpstreamRequestError |
non-429 4xx, nested error with code/type/param (object or Gemini list envelope) |
No — a client-side request mistake passed through the gateway, terminal. | Fix the flagged model or parameter (.code / .param); if model_not_found, request the model in API Manager. |
ModelNotRoutable |
400, flat error saying the model "is not in the known unique model map" (model-based routing with more than one provider), "Missing 'model' field in request", or "Unsupported provider '…'. No fallback configuration." |
No — a client configuration mistake, terminal; the upstream was never called. | For a bare model name, use the provider/model form, e.g. openai/gpt-5-mini instead of gpt-5-mini. For a missing model, send the model where the proxy's format expects it (the model body field for OpenAI ingress, the URL path for native Gemini ingress), with the client that matches the proxy's format. For an unsupported provider (.provider), use a provider the proxy routes to, or ask the proxy owner to add a route or a fallback for it. |
UpstreamModelError |
5xx |
Yes — the transport already retries a 503, and a 502 / 504 too unless the request was a model call (set retry_model_calls_on_gateway_errors to include those); a persistent 5xx is safe for you to retry once you accept a possible second charge. |
Transient provider failure — retry, then escalate if it persists. |
GatewayUnavailable |
transport failure — DNS, refused connection, TLS, timeout — with no HTTP response | Not automatically — terminal here; you may retry or fall back. | Check host reachability, .base_url, and network egress; run donkey doctor. |
ApprovalError |
client-side base of ApprovalRejected (a reviewer refused a framework-paused tool) and GatewayApprovalDenied (the user refused the gateway's step-up). Catch it to handle both refusals at once. |
No — the call was refused at its approval step. | Tell the user or the agent that the action was not authorized; don't retry it unchanged. |
ApprovalNotFound |
client-side, also a KeyError: donkey.approvals.get, resolve or reject of an id this Donkey holds no pending approval for. It was already decided, another Donkey recorded it, or the process restarted. .approval_id is the id. |
No — the same id is never pending again. | Decide each approval once, on the Donkey that recorded it. After a restart, call the tool again to ask for a fresh decision. |
DescriptorMismatch |
client-side, also a ValueError, from donkey_kit.experimental: derive_descriptor(..., mode="auto:check") derived a descriptor that differs from the committed file. |
No — the code and the file disagree until one changes. | Regenerate the committed descriptor with mode="auto" if the change is intended, or fix the tool definition. |
More DonkeyErrors are client-side signals, not gateway refusals, so
they sit outside the retry question. BudgetReserveReached is raised before a
call by donkey.budget.pace() and is meant to be recovered from
(await donkey.budget.wait_for_reset(), then continue) when its .reset_at is
known. If .reset_at is None, propagate or handle it instead — waiting returns
immediately and an unconditional retry would spin. Its .remediation carries
that branch as an inspectable next step, so you don't have to parse the
exception message. ModelSubstituted reports that a call succeeded against a
different model than requested (opt-in via on_model_substitution="raise").
ApprovalRequired and ApprovalTimedOut come from a
@donkey.tool(approval="required") tool: the first means the tool is
waiting for a human decision, the second that nobody decided in time.
ApprovalRejected comes from a gated tool that LangGraph paused and a reviewer
refused on resume. None of them is a PolicyViolation, and refusal handlers
never see them. ApprovalRejected shares the ApprovalError base with the
gateway's GatewayApprovalDenied, and ApprovalNotFound means the id is not
pending on this Donkey (see Resolving).
A native approval resume with missing requester evidence raises AuthError
without running the tool, even if the framework kept its durable pause.
Changed approval values or exact types, custom objects in reviewed arguments,
and cyclic argument data raise ConfigError. The ADK plugin's trusted injected
ToolContext is execution-only and identity-checked, not reviewed data.
Request a fresh approval with unchanged acyclic built-in data;
see Human approval.
ConfigError is raised locally, before any request. It reports every missing
field at once, and it also reports an endpoint that may not receive the
configured credentials: a non-https:// URL, or a URL from the project's config
files paired with credentials from elsewhere. See
Which credentials a URL receives.
Fix the config and re-run. The transport raises ConfigError for two lifecycle
mistakes as well, so neither escapes as a bare RuntimeError: a call on a
Donkey whose HTTP client is closed (after aclose(), or after a framework
closed the client it was given), and a call whose pooled connections belong to
an event loop that has closed. The SDK's own connection pools are per event
loop, so a second asyncio.run() on one Donkey works; this one comes from a
transport you passed in and reused across asyncio.run() calls. Its
.remediation names the fix for each. Outside a donkey.run()
block, typed_refusals() or @donkey.governed, it reaches you the way
GatewayUnavailable does: openai before 3 and anthropic wrap it in an
APIConnectionError (read the ConfigError from e.__cause__), and openai
3 and later raises it as it is. Inside those blocks it is the typed
ConfigError either way.
AuthError.remediation follows the plane that failed. Errors classified from
an LLM-proxy response use the canonical consumer-credential guidance that
donkey doctor also prints. Control-plane token failures override that
default with guidance for the provider that failed: connected-app errors point
to the Anypoint credentials and scopes, while an exhausted ChainedAuth points
to each configured provider's credential or token source. A registry read the
connected app is not allowed to make names the scope it needs and the business
group to grant it on; see Connected-app scopes.
Every rejection above describes something the gateway told the SDK.
GatewayUnavailable is the opposite: a transport-level failure — DNS, refused
connection, TLS error or timeout — with no HTTP response behind it. It is the
one ungoverned failure the taxonomy names, so a long-running agent can tell
"lost the gateway" apart from any other network fault and react — checkpoint,
queue, shed load, or fall back to a non-AI path — instead of pattern-matching a
raw httpx exception.
DonkeyAsyncClient and its blocking twin both raise it, so the async and sync
surfaces behave identically. What reaches your code depends on the SDK on top.
openai before 3 and anthropic re-wrap it as an APIConnectionError with the
GatewayUnavailable on __cause__; openai 3 and later lets it through as
GatewayUnavailable. Inside donkey.run() or @donkey.governed it reaches you
as GatewayUnavailable in every case, unless you opt out with
typed_refusals=False (see
Typed refusals at the framework boundary).
It is terminal and not retried. It carries:
.base_url— the origin that failed, on the exception, not only in the message..cause— the underlyinghttpxexception (also chained viaraise … from)..request_id— alwaysNone; there was no response to read the upstream provider's id from..correlation_id/.call_id— the run and per-call ids the client sent, carried even though no response came back, so the failure joins your logs like any other.
Its .remediation names the three real causes — an unreachable host, a wrong
base URL, or blocked network egress — and points at donkey doctor for
connectivity diagnosis.
Every DonkeyError — not just every refusal — carries a non-empty,
human-readable remediation, so except DonkeyError as e: log(e.remediation)
is always safe. The constructor raises if you try to build one with a blank
remediation, every class accepts a remediation= override, and each class ships
a canonical default. For the refusals:
PIIDetected→ remove or redact the flagged values, or relax the policy's entity list in API Manager.AgentKilled→ ask an administrator to restore this agent's model access in Governance > Security.GatewayApprovalPending→ re-send the same request afterretry_afterseconds; it succeeds once the user approves.GatewayApprovalDenied→ tell the user the action was not authorized.TokenBudgetExceeded→ wait for the window to reset (seeretry_after) or request an increase.RequestRateLimitExceeded→ wait for the window to reset (seeretry_after) or request an increase.PromptInjectionBlocked→ review and sanitise the untrusted input, or adjust the policy's sensitivity.ContentSafetyBlocked→ revise the flagged content, or adjust the policy's categories / severity thresholds.
The text names the action you can take, not the policy that fired. Because
each default lives on the exception class, it is a single source of wording that
donkey doctor reuses for its own failure output, so the CLI and the
exception never disagree.
The LLM PII policy's rejection text repeats every value it flagged. PIIDetected
builds its own message instead, from the entity types, their count and their
character offsets. So str(exc), repr(exc) and exc.args never contain the
blocked value, and neither does a log line, a traceback or
donkey doctor:
Request blocked: personally identifiable information detected (403): 1 entity (Email at chars 12-32). Values withheld; the gateway's text is on .gateway_message.
.entities lists canonical types (SSN, Email, CreditCard, PhoneNumber,
Custom); unrecognised or custom labels become Custom, so a label cannot
smuggle a blocked value into rendered output. The gateway's own text is on
.gateway_message, and the raw body is on .response. Neither is rendered by
str() or repr(). Both carry the blocked content, so handle them like the
prompt itself. For MCP PII, use the safe projection described above instead;
the raw diagnostics are not copied to .gateway_message. The other refusal messages are built from status codes,
headers, category names and policy pattern names, never from the request.
ContentSafetyBlocked.provider names the moderation provider that blocked the
call, as a stable slug: azure-content-safety, bedrock-guardrails,
google-model-armor or crowdstrike-aidr. .categories lists what it flagged
(["rai_dangerous"]). The refusal's span carries the same two values as
donkey.policy.provider and donkey.policy.categories
(Telemetry).
A traceback also prints every chained exception, and a framework's own error
usually repeats the gateway's text. So when the SDK maps a framework error to
a typed one, as donkey.run() and
typed_refusals() do, it raises
it without a chained cause: exc.__cause__ is None, and the
framework error is on exc.framework_error (None when there was none). No
frame in the traceback holds the framework error as a local variable, so error
reporters that print frame locals (Sentry, pytest -l) don't show it either.
Python still keeps it on the suppressed exc.__context__, so treat
framework_error and __context__ like gateway_message.
This applies to policy refusals. UpstreamRequestError messages include the
upstream provider's own error text, which can quote parts of your request. For
everything the SDK does and doesn't hide in printed output, see
What printed output hides.
Every exception in the tree carries three ids so you can join a failure to your logs and to the gateway's own record:
| Attribute | What it is | Provenance |
|---|---|---|
.correlation_id |
The run id, shared by every call in a donkey.run() block |
The X-Correlation-Id request header the client sent — always equals what went on the wire. |
.call_id |
The per-call id, unique per logical request and stable across that request's retries | The X-Donkey-Request-Id request header the client sent. Present even when the request fails before any response (a transport error). |
.request_id |
The upstream provider's own id, passed through by the gateway | Read back from a response header whose name varies by provider (x-request-id for OpenAI, x-amzn-requestid for Bedrock, apim-request-id for Azure, request-id for a native Anthropic proxy). Quote it to the provider's support team. Absent on a transport error, or on a route where the provider forwarded none. |
classify(response) fills .correlation_id and .call_id from the response's
own request, so a refusal typed at the framework boundary (below) needs no extra wiring — the
correlation id on the exception equals the header that was actually sent. (If you
overrode the header names in config, pass the ids to classify() explicitly.)
Every framework between your code and the gateway raises its own errors. The
OpenAI and Anthropic SDKs turn a refusal into a PermissionDeniedError.
A lost gateway becomes an APIConnectionError with the GatewayUnavailable
hidden on its __cause__ under openai before 3 and under anthropic, while
openai 3 and later raises GatewayUnavailable as it is. LangChain re-wraps
these again, and Strands and Agent Framework wrap them in their own types. Inside a
donkey.run() block or a
@donkey.governed function, none of that reaches
you: a refusal or a lost gateway leaves the block as its typed DonkeyError,
so one except covers every framework.
from donkey_kit import GatewayUnavailable, PIIDetected, TokenBudgetExceeded
client = donkey.openai()
try:
async with donkey.run(id=ticket.id):
resp = await client.chat.completions.create(model="gpt-4o", messages=msgs)
except PIIDetected as e:
print("blocked, entities:", e.entities)
except TokenBudgetExceeded as e:
print("slow down; retry after", e.retry_after, "s")
except GatewayUnavailable as e:
print("could not reach the proxy:", e.base_url)The same block around a LangGraph graph.ainvoke(...), an Anthropic
messages.create(...) or a Strands agent raises the same classes. The
blocking forms behave the same: with donkey.run(): and a sync
@donkey.governed function.
Outside a run, typed_refusals() is the same bridge on its own. It works as a
sync or async context manager and as a decorator for sync and async functions,
and every adapter exposes it as donkey.<framework>.typed_refusals():
from donkey_kit import typed_refusals
with typed_refusals():
reply = client.chat.completions.create(model="gpt-4o", messages=msgs)
@typed_refusals()
async def answer(question: str) -> str: ...What the bridge types, and what it leaves alone:
- A typed error the SDK raised, such as
GatewayUnavailableorModelSubstituted, is found on the framework error's cause chain and re-raised as it is. - A gateway rejection is classified from the response the framework
error carries, with the correlation and call ids that were sent, exactly as
classify()would. Only a response the SDK's own transport sent is classified. A403from some other HTTP call in the block is not a governed refusal and passes through. - Anything else propagates unchanged: your own bugs, your own
raise HTTPException(...) from exc, aKeyboardInterrupt, a task cancellation.
The bridge is on by default in both forms. The framework's own error stays on
exc.framework_error (it is None when the SDK raised the typed error itself,
as openai 3 and later does for GatewayUnavailable). To get the framework's
errors instead, pass typed_refusals=False to donkey.run() or
@donkey.governed.
A refusal raised in an asyncio.TaskGroup (or an anyio task group) reaches the
bridge wrapped in an ExceptionGroup. The bridge looks at each leaf:
- Every leaf is the same refusal class: the typed error is raised in the
group's place, so a plain
except PIIDetectedstill works. When several tasks were refused alike, you get the first one. - The leaves are mixed (two refusal classes, or a refusal next to your own
bug): the group is kept, with the same shape, and each refusal leaf is
replaced by its typed error. Catch it with
except*. - No leaf is a refusal: the group propagates unchanged.
import asyncio
from donkey_kit import PIIDetected
try:
async with donkey.run(id=ticket.id):
async with asyncio.TaskGroup() as tg:
tg.create_task(summarise(ticket))
tg.create_task(classify_intent(ticket))
except* PIIDetected as eg:
print("blocked:", [e.entities for e in eg.exceptions])except* also catches the collapsed case, because it wraps a lone exception
in a group before matching. On Python 3.10, which has no builtin
ExceptionGroup, the bridge recognises the exceptiongroup backport's groups
that anyio raises.
classify() is the building block underneath. Apply it to any
openai.APIStatusError (or Anthropic status error) you caught yourself:
import openai
from donkey_kit import PIIDetected, classify
try:
resp = await client.chat.completions.create(model="gpt-4o", messages=msgs)
except openai.APIStatusError as e:
governed = classify(e.response) # -> a DonkeyError subclass
if isinstance(governed, PIIDetected):
print("blocked, entities:", governed.entities)A shape registered with classify.register() comes back as
its registered type here too.
The blocking client from donkey.llm.client(sync=True) behaves identically here.
Drop the await: it is the same OpenAI SDK raising the same
openai.APIStatusError, and classify() reads the response the same way.
The ordinary model/control-plane clients retry only transient upstream/gateway failures (502/503/504).
A 502 or 504 on a model call is not re-sent unless you set
retry_model_calls_on_gateway_errors, because the provider may already have
billed it. Every 4xx is terminal — including a 429: on this proxy a 429 is a
token-budget refusal (TokenBudgetExceeded) or a request-rate-limit refusal
(RequestRateLimitExceeded), so retrying it would only burn the
same already-exhausted window. retry_after is still surfaced for you to pace
against, but the transport never silently retries it. To wait out the reset,
or to react to any other refusal, register a refusal handler
(donkey.on(TokenBudgetExceeded).wait_for_reset(max_wait="45m")). It is
opt-in and bounded, and it re-sends only as a new governed request.
In jwt mode the async client additionally refreshes the wallet JWT and
retries once on a 401. In the default client-id mode the data-plane client
holds no token, so a 401 is terminal, as it is on the blocking client, and
surfaces immediately as AuthError. A CIBA 401 (GatewayApprovalPending) is
not a credential failure, but in jwt mode it still triggers that one refresh
and re-send before it reaches you; the re-send just gets "pending" again. The Anypoint control-plane credential
lives on a separate client: model calls never fetch, send or refresh it. See
What the SDK sends where.
The scoped outbound A2A plane is different: no automatic replay, including
401 refresh/re-send, every 5xx, refusal-handler actions and stream
resubscription. Model retry settings do not override this. The captured v0.3
auth-required task with complete authChallenge metadata raises
GatewayAuthRequired, carrying a frozen challenge and returned task/context
IDs. It is not a refusal, CIBA polling outcome, or completed OAuth flow.
Unknown layouts and v1 tasks stay SDK responses. See
Authentication challenges.
Leaving a stream context cleans up locally, not by cancelling the remote task.
The facade is OFFLINE-VERIFIED; successful gateway send and SSE are NOT live
verified by this implementation yet. Refusal captures do not prove SSE success.
To watch the retries and the token refresh happen, turn on the SDK's debug logging. It records each retry with its status and delay, the 401 refresh, a routing fallback that is not retried, and an auth provider falling through to the next one.
Any content-moderation or federated-guardrail response that matches none of the
discriminators above falls through to a generic PolicyViolation rather than an
invented type. DDK only types a refusal by a discriminator it can identify
reliably; everything else stays inspectable via .response. The message says
the shape is unconfirmed and names the status and any x-llm-proxy-* headers
it carried.
The CrowdStrike AIDR Guardrails policy is the one typed shape that has not been
captured from a live gateway. No proxy running it is available yet, so DDK read
its x-llm-proxy-crowdstrike-aidr-* headers and body from the policy's own
source (crowdstrike-aidr-guardrails-policy 1.0.0) and types an AIDR 403 as
ContentSafetyBlocked(provider="crowdstrike-aidr"). The
verification ledger
records it at VERIFIED (POLICY SOURCE) until a live capture replaces it. If
your proxy sends a different shape, the call falls through to a generic
PolicyViolation here; please file an issue with its status and headers.
Because the shape is built in, classify.register() refuses a rule that
matches it.
Two native-ingress responses land here on model-based-routing 1.0.5. A body
that is not valid JSON gets a 400 {"error":"Invalid JSON body: …"} with
no routing headers, on every ingress Format; the SDK's own clients always send
valid JSON, so you only see it from a hand-built request. On a
Format=Anthropic proxy, a bedrockanthropic/ model is routed to Bedrock
and then answered with a text/plain 404. Both come back as an unconfirmed
PolicyViolation.
One 400 that used to land here is now typed: a bare model name (gpt-5-mini)
sent to a model-based proxy with more than one provider. The gateway rejects it
before any upstream call, and classify() returns ModelNotRoutable. It keeps
the gateway's text and is not a PolicyViolation. The same goes for the
gateway's 400 saying "Missing 'model' field in request", which is what an
OpenAI client pointed at a native Gemini proxy gets back: ModelNotRoutable
with .model set to None. And a provider/model whose provider the proxy has
no route for, with no fallback configured, gets a 400 saying "Unsupported
provider '…'. No fallback configuration.": ModelNotRoutable with .provider
set to the provider the gateway named.