Loading
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.
Recommended by author
This prompt takes no variables — just pick a model and run.
# 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)](https://docs.arcade.dev/en/guides/create-tools/error-handling/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
```python
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.
```python
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 pathsRunning prompts needs a free account.
Sign in and we'll stream the response from Claude Opus 4.7 right here — no config needed for the platform models.
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)](https://docs.arcade.dev/en/guides/create-tools/error-handling/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
```python
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.
```python
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