Build Error Adapter

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.