​

Error Handling

​

Error Format

{
  "error": {
    "message": "Human-readable description",
    "code": "MACHINE_CODE",
    "suggestion": "How to fix this — designed for LLM agents to self-correct",
    "retryable": false,
    "details": {}
  },
  "requestId": "req_abc123"
}

​

Common Error Codes

​

Errors over MCP

• Protocol errors (unknown tool, bad params, insufficient scope) come back as a JSON-RPC error object. The error.data carries suggestion and retryable, mirroring the REST contract.
• Execution failures (the tool ran but failed) come back as a normal tools/call result with isError: true. The content[].text payload includes the failure message followed by a Suggestion: line so the calling model can self-correct.

​

Best Practices

1. Check retryable — if true, retry with exponential backoff; if false, reformulate the request instead of retrying
2. Read suggestion — it tells agents exactly how to fix the issue
3. Log requestId — include it when contacting support
4. Handle code programmatically — don’t parse message strings