# Errors and retries

> Recover from invalid requests, changing availability and expired credentials.

Canonical: https://bookwise.live/docs/errors

MCP server version: 1.1.0

## A predictable domain-error shape

### Example domain error

```json
{
  "isError": true,
  "structuredContent": {
    "code": "SLOT_UNAVAILABLE",
    "message": "The requested option is no longer available.",
    "retryable": false,
    "alternatives": []
  }
}
```

MCP transport failures and SDK input validation may not use this structured shape. Check the protocol/client error and text content as well. Never display internal stack traces or credentials to a customer.

## Choose the next action

| Code | What to do |
| --- | --- |
| VALIDATION_ERROR | Fix the reported fields. Inspect the business bookingParamsSchema. |
| SLOT_UNAVAILABLE | Check availability again and offer returned alternatives; do not silently switch options. |
| HOLD_EXPIRED | Create a new hold after checking availability. |
| VERIFICATION_FAILED | Ask for the correct code; respect attempt limits. Do not guess. |
| PAYMENT_REQUIRED / APPROVAL_PENDING | Follow the payment or approval step; the booking is not confirmed. |
| UNAUTHORIZED / FORBIDDEN | Check the credential type, session expiry, endpoint scope and business ownership. |
| HOLD_NOT_FOUND | Check the parent booking ID and token; invalid tokens may intentionally look like missing bookings. |
| BUSINESS_NOT_FOUND / OFFERING_NOT_FOUND | Refresh discovery and use a currently published business or offering. |
| INVALID_STATE | Fetch progress; the requested transition is not valid for the current status. |
| POLICY_VIOLATION | Explain the business constraint. Offer an allowed option or contact the business. |
| BOOKINGS_PAUSED | The business isn't taking online bookings right now. Give the customer its phone, email or website from get_business instead. |
| RATE_LIMITED | Wait for retryAfterSeconds when returned; avoid tight polling. |
| INTERNAL_ERROR | Retry with backoff if retryable. Preserve an existing mutation's idempotency key. |

## Request and verification limits

The server currently allows 60 read calls, 10 create_hold calls, and 5 confirm/write calls per minute per IP/client identity. New management writes share the confirm bucket. Provider and business-level limits can apply as well.

Booking verification allows at most five code attempts. A resend requires 60 seconds and allows at most three resends per hold without resetting attempts or extending the reservation. Recovery has its own ten-minute code lifetime, five-guess limit and per-booking request limits.

## Connection troubleshooting

- 404 at a business endpoint: check the slug and published state.
- Owner tools listed but denied: public tool discovery does not authenticate an owner. Supply a valid session and owned businessId.
- Local URL unreachable: remote assistants cannot normally reach your computer's localhost.
- Waitlist alert not sent: the requested option may still be unavailable, expired, or waiting for the background worker/provider.
- Reschedule rejected: the option or price may have changed, or the replacement needs a financial adjustment or fresh approval.