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.
Claude detects “No sign-in” when adding brightplace	Select Sign in now and Use Claude’s published identity; leave Request headers empty. Public tool discovery does not grant tool access.
An organization member can see brightplace but cannot use its tools	In the standard OAuth setup, each member must Connect and sign in to their own brightplace account. Adding the connector does not share the owner’s login.
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.
`submit_tour_request` returns `BOOKING_LIMIT_REACHED`	The renter already has 2 active tour requests in the last 24 hours; wait before submitting another.
`submit_tour_request` returns `SLOT_NOT_AVAILABLE`	Re-fetch open slots with `get_listing_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