Tool Execution Errors

When an extension tool fails, Scrydon returns a stable TOOL_VENDOR_* code rather than the underlying error. This page lists every code, what causes it, and what to do about it.

What a failure looks like

A failed tool call returns:

{
  "success": false,
  "output": {},
  "error": "TOOL_VENDOR_EGRESS_DENIED",
  "message": "The destination is not on the approved egress list for this connection.",
  "metadata": { "retryable": false }
}

In a workflow execution the same code appears against the node that failed:

{ "failedNodes": 1, "errors": ["b40d978e-…: TOOL_VENDOR_EGRESS_DENIED"] }

Branch on error. message is a human-readable sentence for that code, meant for whoever reads the failure — it is stable per code but may be reworded, so it is not a branch key. It is selected by the code and never interpolates the underlying reason, so it tells you nothing the code did not already.

Policy blocked the call

Governance refused the request. These are decisions, not faults — retrying an identical request always fails the same way.

Limits and deadlines

The tool or its archive failed

The platform could not run it

These are infrastructure conditions. On Scrydon Cloud they are ours to fix; if you self-host, they point at your deployment.

When to retry

Do not infer retryability from the code. Read metadata.retryable — it is set from the failure's transport characteristics, so the same code can be retryable in one case and not in another.

As a rule:

• Never retry a policy denial. The decision is deterministic.
• Retry with backoff on capacity and transport conditions, and only when the operation is safe to repeat.
• Never auto-retry a side-effecting call after a timeout without reconciling first — a timeout does not prove the request did not commit.
• Wait at least retryAfter seconds when the failure carries one. It is the provider's own requested back-off, and a retry that lands sooner meets the same limit.

In your extension, report a non-OK provider response with throwExtensionHttpError(response) from @scrydon/sdk-authoring/extensions/extension-failure rather than a bare Error. It carries the HTTP status and the provider's error code and, when the provider sent a retry-after-ms or retry-after header, its back-off as retryAfter in whole seconds. The platform forwards that value as the error's retryAfter and the response's Retry-After header — a bare Error loses all three, so every caller can only guess.

What the platform already did before answering you

The platform applies that last rule to itself, so the failure you receive is not the first thing that went wrong — but for a tool call, it is the only thing.

Each platform operation declares whether it is safe to repeat. For a read-only one, a transient provider failure is retried internally (bounded, with backoff, against the same provider — a retry is never permission to switch vendors), so a failure that reaches you has already survived those attempts.

Tool execution is not read-only. A governed tool call can file a ticket, post a message, or create a record, so the platform makes exactly one attempt and hands you the failure. The same applies to creating, renewing, or deleting a webhook subscription. Two consequences:

• A TOOL_VENDOR_TIMEOUT reaching you means one attempt timed out — not that three did. The side effect may still have committed.
• If you retry, yours is the second attempt, not the fifth. Budget accordingly, and reconcile first.

Supplying an idempotencyKey does not change this. The platform forwards it to the extension as an ordinary input field; whether the vendor deduplicates on it is the vendor's behaviour, not a platform guarantee, so the platform does not retry on the strength of one.

Getting the real reason

If you self-host, the untruncated reason is server-side. API Platform logs it against Governed vendor tool execution failed:

{
  "code": "TOOL_VENDOR_EXECUTION_FAILED",
  "executionId": "platform-parent-…",
  "childExecId": "exec-…",
  "executionTier": "microvm",
  "planeReason": "…"
}

planeReason is the failure text, bounded to 512 characters. Note that "The operation timed out." there means a client-side budget expired, not that the platform decided anything — usually the sandbox could not be provisioned in time.

On Scrydon Cloud, quote the executionId to support.