opencode-skills-collection 4.0.7 → 4.0.8

package/bundled-skills/n8n-error-handling/references/ERROR_WORKFLOWS.md

@@ -0,0 +1,178 @@
+# Workflow-Level Error Workflows
+
+Per-node error outputs handle the failures you anticipated on the nodes you remembered to wire. A **workflow-level error workflow** is the catch-all for everything else — and for an unattended workflow (scheduled, cron, queue worker), it's the difference between "the job silently stopped three days ago" and "an alert arrived the moment it broke".
+
+What per-node outputs **don't** catch:
+
+- Failures on nodes you forgot to wire.
+- Crashes between nodes.
+- Whole-workflow timeouts.
+- Trigger failures.
+
+When an unhandled error escapes any of those, n8n invokes the designated **error workflow** with the failure context. You build that workflow once; it serves every workflow that points at it.
+
+---
+
+## What the error workflow receives
+
+It starts with an **Error Trigger** node, which fires with roughly this payload:
+
+```json
+{
+  "execution": {
+    "id": "...",
+    "url": "https://your-n8n/workflow/<wfId>/executions/<execId>",
+    "retryOf": "...",
+    "error": {
+      "name": "NodeApiError",
+      "message": "...",
+      "description": "...",
+      "timestamp": 1715000000000
+    },
+    "lastNodeExecuted": "Fetch order",
+    "mode": "trigger"
+  },
+  "workflow": { "id": "...", "name": "Sync Stripe customers" }
+}
+```
+
+Note what's **not** there: the payload carries the error message and the failed node's *name* (`lastNodeExecuted`), but **not the input data** that caused the failure. Recovering that takes an extra step (below).
+
+---
+
+## Minimal error workflow (capture → notify)
+
+For most workflows, this is enough:
+
+```
+Error Trigger → Set (build alert message) → Slack / email (post to #incidents)
+```
+
+Three nodes. Fast, hard to get wrong, and it turns silence into a message. Build it with `n8n_create_workflow` (or the partial-update ops), then assign it in the UI (see "Assigning it" below).
+
+---
+
+## What to put in the alert
+
+A good notification lets on-call act without opening n8n first. Pull these from the payload:
+
+| Field | Expression |
+|---|---|
+| Workflow name | `{{ $json.workflow.name }}` |
+| Workflow ID | `{{ $json.workflow.id }}` |
+| Editor link | `{{ $json.execution.url.split('/executions/')[0] }}` |
+| Execution ID | `{{ $json.execution.id }}` |
+| Execution link | `{{ $json.execution.url }}` |
+| Failed node | `{{ $json.execution.lastNodeExecuted }}` |
+| Error message | `{{ $json.execution.error.message }}` |
+| Error description | `{{ $json.execution.error.description }}` (often empty, useful when set) |
+| Timestamp | `{{ DateTime.fromMillis($json.execution.error.timestamp).toISO() }}` |
+
+The `timestamp` is a Unix-ms number — format it with Luxon's `DateTime.fromMillis(...)`. The execution `url` is `{base}/workflow/{id}/executions/{execId}`, so stripping the `/executions/...` tail gives the editor URL.
+
+A useful Slack body:
+
+```
+Workflow failure: *{{ $json.workflow.name }}* (`{{ $json.workflow.id }}`)
+Open editor: {{ $json.execution.url.split('/executions/')[0] }}
+Failed node: `{{ $json.execution.lastNodeExecuted }}`
+Error: {{ $json.execution.error.message }}
+Execution: {{ $json.execution.url }}
+Time: {{ DateTime.fromMillis($json.execution.error.timestamp).toISO() }}
+```
+
+Two links matter: the **editor link** so on-call can start fixing, and the **execution link** so they can see the exact failed run. Skipping either costs a step. "Workflow failed." is not an alert — it's a notification that you'll have to investigate from scratch.
+
+---
+
+## Featureful version: recover the failing input
+
+The Error Trigger payload tells you *which* node failed, not *what data* broke it. To get the offending payload, fetch the execution with the **n8n** node:
+
+```
+Error Trigger
+  → n8n  (resource: Execution, operation: Get,
+          Execution ID: {{ $json.execution.id }},
+          Include Execution Details: true)
+  → Set  (extract failed-node input from the execution data)
+  → Switch (route by severity)
+        ├── high → PagerDuty
+        ├── med  → Slack #incidents
+        └── low  → Slack #monitoring
+  → Data Table (log for tracking)
+```
+
+"Include Execution Details: true" hits `GET /executions/{id}?includeData=true` and returns the full run data, so you can pluck the failed node's input out of `data.resultData.runData[<lastNodeExecuted>]`. Now the on-call message can carry the actual offending payload (which customer, which order id), not just "node X errored".
+
+Caveats, all of which can turn the error workflow itself into a *new* silent failure:
+
+- **Requires an n8n API credential** on this workflow (Settings → API → personal access token, then attach it to the n8n node). Without it the node throws a 401 — an unhandled error *inside the error workflow*.
+- **Requires the failing workflow to persist execution data** (Save Execution Data, instance default or per-workflow). If it doesn't, the API returns metadata only.
+- **The n8n node call can itself fail** (API down, rate-limited). Wire its error output (`sourceIndex: 1`) to a fallback that still notifies, or the original error vanishes behind a fetch failure.
+
+Minimal is enough most of the time. The featureful version earns its keep on production-critical workflows where on-call minutes matter.
+
+---
+
+## Assigning it (UI only — the MCP can't)
+
+> The error workflow is assigned in the n8n **UI**: per workflow under **Workflow Settings → Error Workflow**, or as an instance-wide default. There is **no community-MCP tool** to set this assignment. `n8n_update_partial_workflow` exposes an `updateSettings` op, but the error-workflow setting is not reliably writable through it — confirm in the UI.
+
+So the agent's job is: **build the error workflow with the MCP, then hand the user the exact UI step** — "Open the failing workflow → Settings → Error Workflow → select '<name>'" — and remind them to do it for *every* unattended workflow (or set the instance default once). Building the workflow without assigning it does nothing; the trigger only fires for workflows that point at it.
+
+---
+
+## When the error workflow fires (and when it doesn't)
+
+**Fires** when:
+
+- A node throws unhandled (not routed via a wired per-node error output).
+- The workflow itself fails (timeout, OOM).
+- A trigger fails (rare, possible for non-webhook triggers).
+
+**Does NOT fire** when:
+
+- A node's error output is wired — even if the handler does nothing. n8n considers the error *handled*.
+- You manually stop an execution.
+- The workflow is paused / inactive.
+
+That second case is the subtle one: **a per-node error output wired to a no-op that drops the data will *suppress* the error workflow.** From n8n's perspective the error was handled, even though it was swallowed. So only catch per-node when you're genuinely acting on the error; if you want a failure to bubble up to the catch-all, leave it unwired.
+
+---
+
+## What the error workflow should NOT do
+
+- **Make external calls that can themselves fail without a fallback.** If the error workflow fails, the original error disappears — you've added a second silent failure on top of the first.
+- **Take significant time.** It runs synchronously; a slow error workflow compounds the original failure's impact.
+
+Keep it fast: parse, notify, return.
+
+---
+
+## The recursion trap
+
+If your monitored workflows alert Slack, and the *error* workflow also alerts Slack, then a Slack outage takes out both — the error workflow fails and the failure goes nowhere. n8n won't re-trigger on its own failure (no infinite loop), but you've lost the alert.
+
+Mitigations:
+
+- **Use a different channel than the monitored workflows.** If everything notifies Slack, the error workflow should use email (or vice versa).
+- **Add a fallback** — write to a Data Table (`n8n_manage_datatable`) if the primary notification fails, so there's always a trace.
+- **Lean on instance-level logging** (server logs, Sentry) so even an error-workflow failure surfaces somewhere outside n8n.
+
+---
+
+## Verifying it works
+
+After building and assigning:
+
+1. Make a throwaway workflow that always fails — e.g. an HTTP Request to an invalid URL, with **no** error output wired so the failure is unhandled.
+2. Run it.
+3. Confirm the error workflow fires and the notification arrives.
+
+This catches the setup mistakes that otherwise stay invisible until a real incident: wrong workflow assigned, wrong channel, missing API credential. Do it once before you rely on the alerting.
+
+---
+
+## Drift watch
+
+The Error Trigger payload shape can shift between n8n versions. If a field isn't where this file says, check current n8n docs and update your expressions — a renamed field fails silently as an empty alert, not a thrown error.

package/bundled-skills/n8n-error-handling/references/NODE_ERROR_OUTPUTS.md

@@ -0,0 +1,171 @@
+# Per-Node Error Outputs
+
+This file is about the **error output on a single node** — the second `main` output that fires when that node throws — and the two-step setup that trips up nearly everyone. For the workflow-level catch-all (Error Trigger workflows) and the webhook/Respond shape, see the rest of `n8n-error-handling`.
+
+The whole point: a node failing should route somewhere *you* control, instead of halting the run. The cost of forgetting half the setup is one of the worst silent-failure modes in n8n — a run that shows green while quietly dropping its work.
+
+---
+
+## The two-step setup (both are required)
+
+Routing a node's failure takes exactly two changes. Either one alone looks finished and misbehaves.
+
+### Step 1 — create the error output
+
+Set `onError: "continueErrorOutput"` on the node. This is what *adds* the second output. Until you do, `main[1]` does not exist and nothing you wire to it can fire.
+
+```javascript
+{ type: "updateNode", nodeName: "Google Sheets",
+  changes: { onError: "continueErrorOutput" } }
+```
+
+Surgical alternative if you're touching only this field:
+
+```javascript
+{ type: "patchNodeField", nodeName: "Google Sheets",
+  fieldPath: "onError", value: "continueErrorOutput" }
+```
+
+The valid `onError` values:
+
+| Value | Effect |
+|---|---|
+| `"stopWorkflow"` (default) | Error halts the whole workflow. The right default for runs you watch. |
+| `"continueRegularOutput"` | The error item flows out the **normal** output (`main[0]`) alongside successes. Rare and usually a mistake — downstream gets error-shaped data and keeps going. |
+| `"continueErrorOutput"` | The error item flows out a **separate** error output (`main[1]`). This is the one you wire below. |
+
+### Step 2 — wire the error output
+
+With `onError: "continueErrorOutput"`, the node has two outputs:
+
+- `main[0]` → success path (`sourceIndex: 0`)
+- `main[1]` → error path (`sourceIndex: 1`)
+
+Wire the error output to a real handler:
+
+```javascript
+{ type: "addConnection",
+  source: "Google Sheets",
+  target: "Handle Error",
+  sourceIndex: 1 }
+```
+
+`sourceIndex: 1` is the error output. (IF nodes accept the friendly aliases `branch: "true"`/`branch: "false"` for index 0/1; a generic fallible node has no such alias — use the explicit `sourceIndex: 1`.)
+
+---
+
+## Failure modes — why "one of two" is so dangerous
+
+### `onError` set, error output NOT wired
+
+```javascript
+// onError: "continueErrorOutput" set on the node,
+// but no addConnection from sourceIndex 1.
+```
+
+On failure the node emits to `main[1]`, which has **no targets**. The error data is silently discarded, downstream never fires, and — this is the trap — the execution is recorded as **succeeded**, because from n8n's perspective the error was "handled" by a branch that happens to go nowhere. No failed execution logged, nothing in the dashboard. The integration "just stops working" and there's no trail.
+
+**Fix:** wire `sourceIndex: 1` to a real handler, *or* set `onError` back to `"stopWorkflow"` so the failure is loud again.
+
+### Error output wired, `onError` NOT set
+
+```javascript
+// addConnection from "Some Node" sourceIndex 1 → "Handle Error" exists,
+// but the node still has the default onError: "stopWorkflow".
+```
+
+The connection sits in the JSON, but the slot it feeds from never fires. The handler is unreachable. On failure the workflow simply **halts** (default behavior). Less dangerous than the first mode — at least it's loud — but the handler you built does nothing.
+
+**Fix:** set `onError: "continueErrorOutput"` on the node.
+
+### Why validation won't save you
+
+A half-wired error output **validates clean**. `validate_workflow` and `n8n_validate_workflow` don't flag "`onError` is set but `main[1]` is empty" or vice versa — both are structurally legal. This is a runtime behavior, not a schema violation. The only reliable check is to read the workflow back (see Verification below).
+
+---
+
+## Common wiring shapes
+
+### Single fallible node → error handler
+
+```javascript
+// Node config: onError: "continueErrorOutput"
+{ type: "addConnection", source: "HTTP Request", target: "Respond Error", sourceIndex: 1 }
+```
+
+### Success path fans out, error path goes elsewhere
+
+```javascript
+{ type: "addConnection", source: "HTTP Request", target: "Save Result",  sourceIndex: 0 }
+{ type: "addConnection", source: "HTTP Request", target: "Notify Slack",  sourceIndex: 0 }
+{ type: "addConnection", source: "HTTP Request", target: "Respond Error", sourceIndex: 1 }
+```
+
+### Multiple fallible nodes → one shared error handler (fan-in)
+
+```javascript
+// Each of these nodes needs onError: "continueErrorOutput" on its own config.
+{ type: "addConnection", source: "Fetch User",     target: "Respond Error", sourceIndex: 1 }
+{ type: "addConnection", source: "Call External",  target: "Respond Error", sourceIndex: 1 }
+{ type: "addConnection", source: "Write Database", target: "Respond Error", sourceIndex: 1 }
+```
+
+Fan-in keeps the graph readable: one error responder, many sources. The handler can inspect which node failed (the error payload carries the failing node's name) to differentiate the response.
+
+### Both log AND respond on the same failure
+
+Wiring the error output to two targets composes without conflict — both receive the error data:
+
+```javascript
+{ type: "addConnection", source: "Call External", target: "Log Full Error", sourceIndex: 1 }
+{ type: "addConnection", source: "Call External", target: "Respond Error",  sourceIndex: 1 }
+```
+
+Useful when you want a sanitized response *and* a private full-detail log on the same failure. (Or chain them: error output → Log → Respond, so the log runs first.)
+
+---
+
+## What counts as "fallible"
+
+Wire an error output on anything that can throw at runtime:
+
+- Network calls — HTTP Request, third-party API nodes, databases.
+- Auth failures — expired credential, rotated token.
+- Schema mismatches — missing DB column, JSON parse failure.
+- Rate limits — 429 from upstream (configure `retryOnFail` first so these self-heal).
+- File/binary operations — missing path, permission denied (see **n8n-binary-and-data**).
+- Code nodes that can throw.
+
+Usually **not** worth an error output:
+
+- Set / Edit Fields on already-validated data.
+- IF / Switch with simple expressions — if those throw it's a bug to fix, not a path to catch.
+- Pure transformations with no I/O.
+
+When unsure, wire it. The cost is one connection; the cost of not wiring it is a silent halt.
+
+---
+
+## Verification (do this every time)
+
+After any create/update, pull the workflow with `n8n_get_workflow` and check **both halves** on each fallible node:
+
+1. **Node config** — `onError` is `"continueErrorOutput"` (or whatever you intended).
+2. **Connections** — `connections["<node>"].main[1]` contains the expected handler(s).
+
+If either half is missing, you have a silent-failure setup. Fix before activating.
+
+`n8n_autofix_workflow` can repair some structural issues, but it won't infer that you *meant* to wire an error path — the intent to handle a given node's failure is yours to express. Treat the read-back as mandatory.
+
+---
+
+## When to use an error workflow instead
+
+Per-node outputs handle the failure of *one node you remembered to wire*. They do **not** catch:
+
+- Failures on nodes you forgot to wire.
+- Crashes between nodes.
+- Whole-workflow timeouts.
+- Trigger failures.
+
+For those, you need a workflow-level **error workflow** (Error Trigger node). And note the inverse: a per-node error output that's wired to a no-op which drops the data counts as "handled" — so it will *suppress* the error workflow. Only catch per-node when you're genuinely acting on the error. See **ERROR_WORKFLOWS.md**.

package/bundled-skills/n8n-error-handling/references/RESPONSE_SHAPES.md

@@ -0,0 +1,220 @@
+# Response Shapes
+
+Conventions for webhook API response bodies — both success and error. The goal is **predictability**: a caller, a dashboard, or a retry loop should be able to branch on your response without guessing. Pick a shape and hold it across every endpoint on the instance.
+
+This file is opinions with reasons. The one hard rule is consistency: **consistency within your project beats consistency with this file.** If your repo or company already has a documented API style, that wins.
+
+---
+
+## First, match what's already on the instance
+
+Before adopting any shape here, look at the API workflows already running and reuse their conventions. A one-off custom shape is hard to undo once callers depend on it, and inconsistency across endpoints is worse than any single choice.
+
+Search with the MCP, then read each result:
+
+```javascript
+search_nodes({ query: "webhook" })          // find webhook-shaped workflows via templates
+n8n_list_workflows({ /* filter */ })          // list workflows on the instance
+n8n_get_workflow({ id: "<id>" })               // read each one's Respond to Webhook nodes
+```
+
+In each existing `Respond to Webhook`, note:
+
+- Top-level keys — envelope vs bare, presence of `error`/`message`/`request_id`.
+- Whether success bodies wrap the payload or return it bare.
+- The exact error-code strings in use (`validation_error` vs `bad_request` vs `INVALID_INPUT`).
+- Header conventions (`Content-Type`, `Retry-After`, `X-Request-Id`).
+
+If results are sparse, mixed, or you can't tell whether a convention exists — **ask the user.** "Endpoints A and B use shape X, C uses Y; which is house style?" saves a future migration. Don't invent a domain prefix or envelope from nothing.
+
+---
+
+## Success shape
+
+Return the data bare. For requests that **create or update** a resource, prefer returning the **full resource** with a 200, not `{ "ok": true }` or just the new ID:
+
+```json
+{
+  "customer_id": "cus_123",
+  "balance": 4200,
+  "currency": "USD",
+  "created_at": "2026-04-25T12:34:00Z"
+}
+```
+
+Returning the resource saves the caller a follow-up GET, lets them confirm what actually persisted (server defaults, normalized values, generated timestamps), and makes the endpoint a single round-trip for a UI that renders the result immediately.
+
+Deviate only when:
+
+- The resource is genuinely large and the caller doesn't need it → return the ID, document why.
+- There is no resource (event ingestion, fire-and-forget) → `{}` or `204 No Content`.
+- The payload is list-shaped → a top-level array, or `{ "items": [...] }` (friendlier to future pagination metadata).
+
+---
+
+## Error shape (the default envelope)
+
+```json
+{
+  "error": "<machine-readable code>",
+  "message": "<human-readable explanation>"
+}
+```
+
+- `error` is a **stable string identifier**, not a sentence. Clients branch on it.
+- `message` is the human version — safe to log, safe to show users *after* sanitization.
+- No `ok: false` flag — the HTTP status code already separates success from failure.
+
+Optional fields by case:
+
+| Field | When to include |
+|---|---|
+| `details` | Validation errors, with a field-by-field map |
+| `retry_after` | Rate limits (also set the `Retry-After` header) |
+| `request_id` | When you run distributed tracing (then on *every* response, not just errors) |
+| `documentation_url` | Public APIs where you want callers to RTFM |
+
+---
+
+## `responseCode` defaults to 200 — set it on every error branch
+
+This is the single most common API error-handling bug, and it's worth its own section because it produces a *worse-than-useless* result: the body says failure while the status says success.
+
+**Every `Respond to Webhook` node defaults `responseCode` to 200** — including the ones you wired to error paths. An error branch that returns 200 with `{ "error": "..." }` looks like success to the caller's HTTP client, so their error handling (which keys off the status code) **never fires**. They process your error body as if it were data.
+
+So: set `responseCode` **explicitly** on every Respond node — not just the success one. (This trap is also documented in **n8n-node-configuration** NODE_FAMILY_GOTCHAS.md, "Webhook / Respond to Webhook".) A workflow can have many Respond nodes, one per response shape; n8n returns whichever fires first.
+
+```json
+{ "responseCode": 502,
+  "responseBody": "={{ JSON.stringify({ error: 'upstream_error', message: 'External service failed' }) }}" }
+```
+
+For paths that differ only by number, set it with an expression instead of fanning out to N nodes — see **API_WORKFLOWS.md**, "5xx: differentiate the body".
+
+---
+
+## Status code → cause
+
+The status code is the caller's first signal; be deliberate.
+
+- **2xx** — success. 200 sync, 202 "accepted, processing".
+- **4xx** — caller's fault. 400 bad input, 401 no auth, 403 not allowed, 404 not found, 409 conflict, 429 rate limited.
+- **5xx** — your fault. 500 unexpected internal, 502 upstream broken, 503 temporarily down, 504 upstream timeout.
+
+Distinguishing 4xx from 5xx matters because the caller's tooling depends on it:
+
+- Caller monitoring alerts on 5xx (your fault) but not 4xx (their fault). Returning 500 for bad input fires *their* pager on *their* bug.
+- 5xx implies "retry", 4xx implies "don't bother".
+- Aggregated error rates segment by class — collapse everything to 500 and you lose that.
+
+### Error codes (a small, stable set)
+
+Adding a code is fine; renaming an existing one breaks callers.
+
+**4xx — caller's fault**
+
+| Code | Meaning |
+|---|---|
+| `validation_error` | Required field missing / type wrong |
+| `invalid_input` | Field present but value invalid |
+| `unauthorized` | No auth or expired auth |
+| `forbidden` | Authenticated but not allowed |
+| `not_found` | Resource doesn't exist |
+| `conflict` | Conflicts with current state (duplicate key, race) |
+| `rate_limit_exceeded` | Too many requests |
+| `unsupported_media_type` | Content-Type wrong |
+
+**5xx — your fault**
+
+| Code | Meaning |
+|---|---|
+| `internal_error` | Catch-all, something failed unexpectedly |
+| `upstream_error` | Third-party API returned an error |
+| `upstream_timeout` | Third-party API didn't respond in time |
+| `service_unavailable` | Temporarily can't process (down, or rate-limited upstream) |
+| `not_implemented` | Operation not supported in this version |
+
+---
+
+## Validation error details (400)
+
+For `validation_error`, include per-field detail so the caller can fix the request without guessing. The Set-node schema validator (API_WORKFLOWS.md) produces this directly:
+
+```json
+{
+  "error": "validation_error",
+  "message": "Validation failed (3 issues):\n• name: Missing required field \"name\"\n• email: \"not-an-email\" is not valid - Contact email address\n• plan: \"premium\" is not allowed. Must be one of: starter, pro, enterprise - Subscription plan",
+  "details": { "name": "Missing required field \"name\"", "email": "\"not-an-email\" is not valid", "plan": "\"premium\" is not allowed" },
+  "request_schema": { "type": "object", "properties": { } }
+}
+```
+
+`message` is the human summary (safe to show), `details` is the structured per-field map (safe to bind to UI fields), and `request_schema` is the schema echoed back so an LLM-driven or programmatic caller can self-correct on the next attempt.
+
+---
+
+## Rate-limit responses (429)
+
+```json
+{
+  "error": "rate_limit_exceeded",
+  "message": "Too many requests. Retry after 30s.",
+  "retry_after": "2026-05-08T21:10:05.135Z"
+}
+```
+
+Also set the HTTP `Retry-After` header (in the Respond node's `options.responseHeaders`). Well-behaved clients respect the header without parsing the body.
+
+---
+
+## What NOT to put in an error response
+
+The body goes to the caller. Treat everything in it as public.
+
+| Don't include | Why |
+|---|---|
+| **Stack traces** — `{ "stack": "Error at line 42 of /opt/..." }` | Reveals paths, versions, library names. A gift to attackers, useless to callers. |
+| **Upstream errors verbatim** — `{ "details": "<raw upstream body>" }` | Upstream may embed *their* tokens and PII. Surface "upstream service failed" + a request id; details go to your logs. |
+| **SQL queries** — `{ "query": "SELECT * FROM users WHERE ..." }` | Exposes schema and access patterns. |
+| **Tokens / credentials / auth values** | Even innocuous-looking `headers`, `config`, or `request` fields can carry token values. Audit error bodies — leaks are easier than you'd expect. |
+
+The pattern is always the same: **log the full error privately, return a sanitized message.** See "Don't leak internals" in API_WORKFLOWS.md for the log-then-respond wiring.
+
+---
+
+## Respond node shape (JSON, for the community MCP)
+
+Success:
+
+```json
+{
+  "type": "n8n-nodes-base.respondToWebhook",
+  "name": "Respond Success",
+  "parameters": {
+    "respondWith": "json",
+    "responseCode": 200,
+    "responseBody": "={{ JSON.stringify($json) }}",
+    "options": { "responseHeaders": { "entries": [{ "name": "Content-Type", "value": "application/json" }] } }
+  }
+}
+```
+
+Error:
+
+```json
+{
+  "type": "n8n-nodes-base.respondToWebhook",
+  "name": "Respond Error",
+  "parameters": {
+    "respondWith": "json",
+    "responseCode": 502,
+    "responseBody": "={{ JSON.stringify({ error: 'upstream_error', message: 'External service failed' }) }}",
+    "options": { "responseHeaders": { "entries": [{ "name": "Content-Type", "value": "application/json" }] } }
+  }
+}
+```
+
+Two notes that bite people:
+
+- **Always set `Content-Type: application/json` explicitly.** Default behavior depends on the body shape and isn't reliable.
+- **With `respondWith: "json"`, pass the object, not a stringified string.** If you hand it `JSON.stringify(obj)` it serializes that string *again* and you get a double-encoded body. Either use `respondWith: "json"` with an object expression (`={{ { error: 'x' } }}`), or keep `JSON.stringify(...)` and let the node treat it as the already-final body — pick one and be consistent. (See **n8n-node-configuration** NODE_FAMILY_GOTCHAS.md.)