# Errors and authorization

| Status | code | Meaning | What to do |
| --- | --- | --- | --- |
| 401 | `unauthorized` | No or invalid `x-api-key` (or a session cookie — not accepted here) | Fix the key |
| 403 | `forbidden` | The key's user lacks one or more grants; `details.missing` lists `{ feature, level, scope }` | Use the composite's atomic parts you ARE allowed, or stop and tell the user |
| 403 | `not_entitled` | The hotel's plan lacks `details.feature` | Maison staff can `set_client_features`; otherwise tell the user |
| 400 | `invalid_input` | Zod issues in `details` | Fix the fields and retry once |
| 404 | `not_found` | Unknown id (or unknown tool) | Re-check ids with a list tool |
| 409 | `conflict` | State conflict (duplicate, already running, no capacity) | Read the message; do not blind-retry |
| 413 | `too_large` | Upload over 64 KiB or export over the cap | Use the admin console / narrow the window |
| 503 | `unavailable` | A dependency is down | Retry later |

Grant scopes: `global` = a Maison-staff grant; `client` = a grant on the hotel in `clientId` (or global); `any` = a grant somewhere (list tools filter rows themselves). Levels: READ < WRITE < EXECUTE. Nothing is partially executed: a tool either has every grant or refuses.