Error recovery

Every Pipeworx tool error is structured for self-correcting retries. Agents that read _meta recover from most failures without escalation.

What errors look like

{
  "result": {
    "content": [{ "type": "text", "text": "{\"error\":\"tool_error\",\"message\":\"Missing required parameter: country_code (string)\"}" }],
    "_meta": {
      "alternatives": [
        { "tool": "list_countries", "reason": "Find a valid country_code first" }
      ],
      "examples": [
        { "country_code": "US" },
        { "country_code": "GB" }
      ],
      "retry_hint": "Retry the same tool with arguments matching one of the example shapes.",
      "feedback_hint": "If this looks like a bug in is_today_holiday, file pipeworx_feedback({type:\"bug\", ...}).",
      "tier": "anonymous",
      "cost": { "total": 1, "components": [...] }
    }
  }
}

The standard agent recovery loop:

1. Parse the text content as JSON; if it has error, treat as failure.
2. Read _meta.examples — pattern-match the failed args against a working example. Most of the time this is enough.
3. If you still don’t know how to recover, look at _meta.alternatives — these are tools that solve a related need.
4. Use _meta.retry_hint as natural-language guidance to the model.
5. If the failure looks like a Pipeworx-side issue, the feedback_hint gives you a pre-formatted pipeworx_feedback call.

Error classes

Pipeworx classifies errors at the gateway in _meta:

The class isn’t directly exposed in _meta (it’s used for analytics), but you can usually infer it from the error message. The retry_hint and alternatives are populated regardless.

Pattern: self-correcting on schema mismatch

The most common error is “wrong arg shape.” _meta.examples is the same examples returned in tools/list — repeated here so the model has them in immediate context.

// First attempt
ct_get_study({})
// → error: "Cannot read properties of undefined (reading 'trim')"
// → _meta.examples: [{ "nct_id": "NCT04280705" }]

// Retry with corrected shape
ct_get_study({ nct_id: "NCT04280705" })
// → success

Pattern: alternative-tool fallback

When the failed tool’s wrong tool entirely:

fda_drug_events({ query: "asparafalcomine" })  // not a real drug
// → error: "No results"
// → _meta.alternatives: [
//     { "tool": "rxnorm_search", "reason": "Try resolving the drug name first" }
//   ]

// Pivot
rxnorm_search({ name: "asparafalcomine" })
// → also no match — so the term is wrong, not the tool

// Surface to user: drug name probably typo'd

Pattern: feedback loop on unfixable errors

If you exhaust retries and alternatives, file:

pipeworx_feedback({
  type: "data_gap",
  message: "ct_get_study returned 'Cannot read properties' for valid-looking NCT IDs (NCT09999999); seems to crash on missing studies instead of returning a not-found error.",
  context: { tool: "ct_get_study", pack: "clinicaltrials" }
})

The Pipeworx team reviews feedback daily. Recurring patterns become bug fixes.

What you should NOT do

• Don’t retry the exact same call without reading _meta.examples. If the call failed once with these args, it’ll fail again.
• Don’t silently swallow errors. Surface them to the user with the tool name + the actual error message. Pipeworx errors are informative; hiding them makes debugging harder.
• Don’t loop infinitely. Hard-cap retries at 3 per tool per task. After that, fall back to a different tool or escalate.