Skip to content

Latest commit

 

History

History
671 lines (577 loc) · 47.8 KB

errors.mdx

File metadata and controls

671 lines (577 loc) · 47.8 KB
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'

Governed error taxonomy

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.

The rejection shapes classify() types

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"]
Loading

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.

The exception tree

JSON-RPC refusal matching

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.

MCP PII metadata

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.

Cookbook: every exception — discriminator, retryable, next step

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.

When the gateway can't be reached at all

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 underlying httpx exception (also chained via raise … from).
  • .request_id — always None; 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 refusal names a next step

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 after retry_after seconds; it succeeds once the user approves.
  • GatewayApprovalDenied → tell the user the action was not authorized.
  • TokenBudgetExceeded → wait for the window to reset (see retry_after) or request an increase.
  • RequestRateLimitExceeded → wait for the window to reset (see retry_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.

Refusal messages don't repeat blocked content

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.

The ids every DonkeyError carries

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.)

Typed refusals at the framework boundary

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 GatewayUnavailable or ModelSubstituted, 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. A 403 from 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, a KeyboardInterrupt, 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.

Refusals inside a task group

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 PIIDetected still 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.

The bridge only sees calls that went through the SDK's transport. CrewAI owns its transport, so its errors pass through untyped. This is the same [conformance exemption](/testing#exemptions) as its correlation id.

Classifying a response yourself

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.

Retry behaviour

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.

Unrecognised shapes

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.