REFERENCE
Errors & limits
Tool errors come back as normal MCP results with isError: true and a plain sentence written for the assistant: what went wrong and what to do next.
Common errors
| You see | Why | Do this |
|---|---|---|
HTTP 401 + WWW-Authenticate | A sign-in-only tool was called without a valid token. | Your client runs the OAuth flow, then retries the same call. |
HTTP 429 rate_limited | Too many anonymous requests from one address. | Wait a minute and retry. |
RATE_LIMITED: too many … requests. Try again in N seconds. | A signed-in customer went over a per-minute limit. | Wait the stated seconds. A repeat confirm of a booking that already succeeded is never limited. |
Invalid or expired option | The option_id was changed, or its time has passed. | Call get_availability again and use a fresh option_id unchanged. |
Needs more information before this booking can be prepared: … | A business question is missing or its answer doesn't fit. | Ask the customer exactly what the message lists, then call prepare_booking again. |
EXPIRED: this preparation expired … | More than 15 minutes passed between prepare and confirm. | Prepare again (the customer re-approves the new summary). |
SLOT_UNAVAILABLE | Someone else took the time between prepare and confirm. | Nothing was booked. Offer other times. |
Unknown preparation / Unknown booking | The id doesn't exist, or belongs to someone else. | Use the ids from this customer's own calls. |
… is paused and not taking bookings | The business has paused online booking. | Offer the business's phone number or another business. |
Life-safety guidance + emergency number | The description suggests danger (gas, CO, sparking, smoke …). | Pass the guidance on. Nothing was booked. |
Invalid arguments (a missing required field, a wrong type) are rejected by the MCP layer before the tool runs, with the field named in the message.
Rate limits
| Who | Limit |
|---|---|
| Not signed in (per client address) | 120 requests a minute |
| Signed in: search, details, availability, prepare | 60 a minute |
| Signed in: new confirms | 5 a minute |
HTTP details
- All MCP messages are
POST.GETandDELETEon the endpoint return405(the server is stateless, with no streams or sessions). GET /healthreports liveness.