Skip to main content

​
Error envelope

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.
UNAUTHORIZEDOAuth attribution was requested but the bearer token is missing, invalid, or not accepted for the MCP resource.
TOKEN_EXPIREDThe bearer token is expired. Refresh or reconnect before retrying an OAuth-attributed request.
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 connected service failed.

​
Rate-limited details

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

​
Troubleshooting

SymptomWhat to check
Connector cannot be addedConfirm the URL is exactly https://mcp.brightplace.ai/mcp and uses HTTPS. See the client-specific Install guide.
Client says the server is unreachableConfirm the endpoint resolves over HTTPS from the public internet.
Search returns FAIR_HOUSING_VIOLATIONRephrase using objective criteria such as price, size, location, amenities, and availability. Avoid protected-class or demographic terms.
Tool calls return UNAUTHORIZED or TOKEN_EXPIREDReconnect the account or refresh the bearer token, then retry.
Tool calls return RATE_LIMITEDBack off for at least retry_after_seconds before retrying.
book_tour returns BOOKING_LIMIT_REACHEDThe renter already has 2 active tour requests in the last 24 hours; wait before submitting another.
book_tour returns SLOT_NOT_AVAILABLERe-fetch open slots with get_tour_availability and book a current one.
A tool returns DOWNSTREAM_ERRORA connected service failed transiently. Retry later; if it persists, the data may be temporarily unavailable.