Skip to main content
Tool errors use a stable envelope: 
{
  "ok": false,
  "error": {
    "error_code": "VALIDATION_ERROR",
    "message": "Tool input failed validation.",
    "details": {}
  },
  "latency_ms": 2
}
Clients should handle these error codes and tolerate new codes being added over time.
CodeMeaning
LISTING_NOT_FOUNDThe requested listing_id is unknown.
SLOT_NOT_AVAILABLEThe requested tour slot is no longer bookable.
BOOKING_LIMIT_REACHEDThe renter already has 2 active tour requests from the last 24 hours.
FAIR_HOUSING_VIOLATIONThe request was blocked by Fair Housing guardrails.
VALIDATION_ERRORInput failed schema validation.
TOOL_NOT_FOUNDThe requested tool name is not registered on the server.
RATE_LIMITEDA per-session, aggregate, per-tool, or booking limit was exceeded.
DOWNSTREAM_ERRORA downstream service failed.

​
Rate-limited details

RATE_LIMITED responses include retry information when available: 
{
  "error_code": "RATE_LIMITED",
  "message": "Rate limit exceeded.",
  "details": {
    "reason": "mcp_tool_session_rate_limit_exceeded",
    "limit_scope": "per_tool",
    "limit_type": "tool_session",
    "retry_after_seconds": 1
  }
}
Do not retry immediately. Wait at least retry_after_seconds, then retry only if the user’s request is still relevant.