build-error-adapter

name	build-error-adapter
description	Build new Arcade error adapters from scratch using public Arcade TDK patterns. Use when adding provider integrations, mapping SDK exceptions, or extending HTTP/GraphQL/auth adapter behavior.

Build Error Adapter

Use this workflow to create new error adapters that fit Arcade TDK conventions.

Official Reference

Start here and align behavior with this doc:

• Arcade docs: Providing useful tool errors (Error adapters)

Quick Context

• Adapter protocol: arcade_tdk.error_adapters.base.ErrorAdapter
• Common error classes:
  • arcade_tdk.errors.UpstreamError — upstream responded with an HTTP status code
  • arcade_tdk.errors.UpstreamRateLimitError — 429 / quota-exhausted with retry_after_ms
  • arcade_tdk.errors.NetworkTransportError — no complete response was received (timeouts, connection/DNS/TLS failures, decoding errors, redirect exhaustion). status_code is always None; use one of the NETWORK_TRANSPORT_RUNTIME_* kinds: _TIMEOUT, _UNREACHABLE, _UNMAPPED.
  • arcade_tdk.errors.FatalToolError — unrecoverable tool-authoring bug or environment misconfiguration (invalid URL, unsupported protocol, bad headers, TLS trust failures). Never retried.
  • arcade_tdk.errors.RetryableToolError — transient tool-body failure with a hint for the LLM to retry.
  • arcade_tdk.errors.ContextRequiredToolError — needs human input before retry.

Rules To Follow

1. Keep imports at top-level only (no inline imports), except optional dependency imports that must be lazy by design.
2. Adapter interface contract:
   • slug class attribute
   • from_exception(self, exc: Exception) -> ToolRuntimeError | None
3. Return None when the exception is not recognized for that adapter.
4. Return a ToolRuntimeError subclass for recognized exceptions (UpstreamError, UpstreamRateLimitError, etc.).
5. Preserve privacy:
   • Agent-facing message must be safe.
   • Put raw vendor detail into developer_message when needed.
6. Add tests for every new mapping path.
7. Match your installed Arcade version's decorator API and parameter names.

Privacy Rule When Uncertain

If you are not fully sure what str(exc), vendor reason, or nested payload fields can contain, treat them as potentially sensitive.

• Default to a safe agent-facing message template:
  • "Upstream <Service> request failed with status code <code>."
  • "Upstream <Service> error: unhandled <ExceptionType>."
• Put raw details in developer_message instead of message.
• Prefer structured non-secret context in message (status code, error class, stable provider error code).
• Never put tokens, auth headers, full URLs with query params, raw response bodies, or stack traces in agent-facing message.

Use this decision rule:

1. Known-safe field (documented stable code/reason without sensitive payload): may be included in message.
2. Unknown or mixed-content field: keep out of message; include only in developer_message.
3. High-risk content (headers/body/credential-like strings): never include in message; sanitize or omit even in developer_message if policy requires.

When in doubt, prefer slightly less detail in message and richer diagnostics in developer_message.

Decide: Adapter vs explicit tool error

Use an error adapter when:

• You need repeatable translation from vendor exceptions to Arcade errors.
• The same exception family appears across multiple tools.

Raise explicit tool errors in tool code when:

• You need user guidance for immediate retry (RetryableToolError).
• You need user/orchestrator input before retry (ContextRequiredToolError).
• You need a special business rule for one endpoint/tool path only.

Implementation Pattern

1) Create adapter skeleton

from arcade_core.errors import ToolRuntimeError


class VendorErrorAdapter:
    slug = "_vendor"

    def from_exception(self, exc: Exception) -> ToolRuntimeError | None:
        # recognize typed vendor exceptions
        # return mapped ToolRuntimeError
        return None

2) Use typed exception matching

• Match most specific subclasses first.
• Keep a final typed fallback for broad vendor exceptions.
• Avoid broad except Exception handling inside from_exception.

Example ordering:

1. Rate limit subtype
2. Auth subtype
3. Timeout/transport subtype
4. General vendor exception fallback

3) Normalize metadata

For adapted errors:

• Include extra["service"] = self.slug
• Include extra["error_type"] = type(exc).__name__ for non-status failures
• Include sanitized endpoint/method when available

4) Map status-like semantics consistently

Upstream responded with an HTTP status code → UpstreamError:

• 429 → UpstreamRateLimitError with retry_after_ms
• 5xx → retryable UpstreamError (status_code >= 500)
• 4xx → non-retryable UpstreamError

UpstreamError derives retryability from status code, so predictable behavior is automatic.

No complete response from upstream → NetworkTransportError:

Use this class when the exception inherently means the request never reached the upstream, or no complete response came back. status_code is None by design.

Exception kind	kind=	can_retry=
Timeouts (connect, read, pool)	NETWORK_TRANSPORT_RUNTIME_TIMEOUT	True
Connection refused, DNS, TLS handshake, remote-protocol errors	NETWORK_TRANSPORT_RUNTIME_UNREACHABLE	True
Decoding failures, generic transport fallback	NETWORK_TRANSPORT_RUNTIME_UNMAPPED	True
Redirect-loop exhaustion	NETWORK_TRANSPORT_RUNTIME_UNMAPPED	False

Tool-authoring bugs / local environment misconfiguration → FatalToolError:

Use this class for exceptions that will never succeed on retry — the tool's code or environment needs to change:

• Invalid URL, unsupported scheme, missing scheme, bad headers, malformed local HTTP protocol state
• TLS / certificate / trust configuration failures (ssl.SSLError and siblings)

Do not dress these up as UpstreamError — an UpstreamError implies the upstream service actually said "no". Miscategorizing pollutes telemetry and sends the wrong retry signal.

5) Optional dependency handling

For SDK-specific adapters, lazy-import the SDK module inside from_exception if that dependency may be optional.

• If import fails, log and return None.
• Do not raise import errors from adapter code paths.

Registration Pattern

For httpx and requests, automatic adaptation is typically available.

For SDK-specific adapters, register explicitly on tools.

from arcade_mcp_server import tool
from arcade_tdk.error_adapters import GoogleErrorAdapter

@tool(
    # Depending on Arcade version, this may be `adapters=` or `error_adapters=`.
    adapters=[GoogleErrorAdapter()],
)
def my_tool(...) -> ...:
    ...

If your project uses a different parameter name, follow your installed API docs/signature.

Required Test Matrix

Create or extend tests in your project test suite:

• recognized typed exception -> expected ToolRuntimeError subclass
• expected status_code, kind, can_retry
• expected extra keys (service, error_type, endpoint/method when applicable)
• unknown exception returns None
• optional dependency missing path returns None
• privacy split is verified:
  • message stays safe for uncertain/raw exceptions
  • developer_message carries deep diagnostics

Done Checklist

• Adapter returns ToolRuntimeError | None
• Safe agent-facing messages
• Uncertain exception content defaults to safe templates
• Typed exception coverage added
• Tests added/updated and passing
• Any required package versioning updated for your repo rules
• No noisy stdout/stderr output in MCP tool runtime paths