> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brightplace.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors & Troubleshooting

> The brightplace Connect error envelope, error-code set, and common fixes.

## Error envelope

Tool errors use a stable envelope:

```json theme={null}
{
  "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`           | OAuth attribution was requested but the bearer token is missing, invalid, or not accepted for the MCP resource. |
| `TOKEN_EXPIRED`          | The bearer token is expired. Refresh or reconnect before retrying an OAuth-attributed 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.                                                                                     |

## Rate-limited details

`RATE_LIMITED` responses include retry information when available:

```json theme={null}
{
  "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](/install/claude) 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 `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.                             |