Skip to main content

Error Handling

Error Envelope​

Tool call failures typically return one of these classes:

  • upstream_http_error
  • upstream_timeout
  • network_exception
  • missing_required_credentials

Common Patterns​

Upstream Timeout​

{
  "ok": false,
  "classification": "upstream_timeout",
  "message": "Upstream MCP request timed out."
}

Missing Credentials​

{
  "ok": false,
  "classification": "missing_required_credentials",
  "message": "Credential setup is incomplete for this service."
}

Session Recovery​

If an upstream returns missing session or session not found, the broker will attempt one automatic recovery cycle (initialize + retry).

Retry Guidance​

  • Safe to retry idempotent read calls.
  • For write calls, prefer idempotency keys or upstream-safe retries.
  • For long Qdrant ingestion jobs, prefer source_url and monitor timeout budget.