Errors & Troubleshooting

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.

Code	Meaning
`LISTING_NOT_FOUND`	The requested `listing_id` is unknown.
`SLOT_NOT_AVAILABLE`	The requested tour slot is no longer bookable.
`BOOKING_LIMIT_REACHED`	The renter already has 2 active tour requests from the last 24 hours.
`FAIR_HOUSING_VIOLATION`	The request was blocked by Fair Housing guardrails.
`UNAUTHORIZED`	The operation requires an authenticated account. Reconnect before retrying.
`TOKEN_EXPIRED`	The bearer token is expired. Refresh or reconnect before retrying the tool request.
`VALIDATION_ERROR`	Input failed schema validation.
`TOOL_NOT_FOUND`	The requested tool name is not registered on the server.
`RATE_LIMITED`	A per-session, aggregate, per-tool, or booking limit was exceeded.
`DOWNSTREAM_ERROR`	A connected service failed.

HTTP authentication challenge

Authentication can fail before a tool runs. Missing or invalid authentication returns HTTP 401, a WWW-Authenticate header with resource_metadata, and:

{"error": "invalid_token", "error_description": "Authentication required"}

This is separate from the tool envelope above. It also covers expired tokens; clients should not depend on a distinct TOKEN_EXPIRED response. Refresh if supported, or reconnect the account and retry. initialize and tools/list remain available before sign-in.

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

Symptom	What to check
Connector cannot be added	Confirm the URL is exactly `https://mcp.brightplace.ai/mcp` and uses HTTPS. See the client-specific Install guide.
Client says the server is unreachable	Confirm the endpoint resolves over HTTPS from the public internet.
Search returns `FAIR_HOUSING_VIOLATION`	Rephrase using objective criteria such as price, size, location, amenities, and availability. Avoid protected-class or demographic terms.
Tool calls return HTTP `401`, `Authentication required`, `UNAUTHORIZED`, or `TOKEN_EXPIRED`	Reconnect the account or refresh the bearer token, then retry.
Tool calls return `RATE_LIMITED`	Back off for at least `retry_after_seconds` before retrying.
`book_tour` returns `BOOKING_LIMIT_REACHED`	The renter already has 2 active tour requests in the last 24 hours; wait before submitting another.
`book_tour` returns `SLOT_NOT_AVAILABLE`	Re-fetch open slots with `get_tour_availability` and book a current one.
A tool returns `DOWNSTREAM_ERROR`	A connected service failed transiently. Retry later; if it persists, the data may be temporarily unavailable.

brightplace Connect

Tool Reference

Security and Policy

Error envelope

HTTP authentication challenge

Rate-limited details

Troubleshooting

​Error envelope

​HTTP authentication challenge

​Rate-limited details

​Troubleshooting

Error envelope

HTTP authentication challenge

Rate-limited details

Troubleshooting