> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mattone.co/llms.txt
> Use this file to discover all available pages before exploring further.
# Troubleshooting KrossBooking: sintomi, cause e soluzioni
> Tabella sintomo → causa → soluzione per diagnosticare e risolvere i problemi più comuni dell'integrazione KrossBooking su Mattone.
Usa questa pagina per diagnosticare i problemi dell'integrazione KrossBooking: identifica il sintomo che stai osservando, verifica la causa più probabile e applica la soluzione indicata. Prima di assumere una causa, leggi sempre il log effettivo, il messaggio di errore visibile nell'interfaccia è spesso diverso dall'errore reale riportato dalla risposta API.
## Tabella di diagnosi
| Sintomo | Causa probabile | Soluzione |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Auth fallita (401)** | Credenziali errate o scadute | Verifica `hotel_id` + `username` + `password` con lo studente; se scadute, ruotale nel portale Kross e aggiorna il Vault |
| **Rate limit (429)** | Troppe richieste per struttura in un intervallo breve | Attendi il backoff automatico del gateway; se il problema è ricorrente, riduci la frequenza di polling o abilita il coalescing contattando il team tecnico |
| **Disponibilità "sempre occupato"** | Endpoint sbagliato (`get-calendar`) o skill `check-availability` mancante in Conduit | Verifica che il flusso usi `GET /v5/calendar/get-availability`; controlla che la skill `check-availability` sia presente e attiva nella configurazione Conduit dello studente |
| **Foto appartamento mancanti** | Endpoint foto non implementato o `listing_id` errato | Verifica che il `listing_id` in Notion coincida con quello presente in KrossBooking; se l'endpoint foto non è implementato per la struttura, segnalalo al team tecnico |
| **Prenotazione non trovata** | `listing_id` non allineato tra KrossBooking e la Knowledge Base di Conduit | Apri la scheda studente in Notion, verifica il `listing_id` e assicurati che sia lo stesso usato nello scope della KB di Conduit |
| **Dati prenotazione vuoti** | Filtri data ignorati server-side, la risposta è vuota perché i filtri non vengono applicati come atteso | Esegui la chiamata senza filtri e valida la risposta completa; vedi [Rate Limit & Trappole](/integrazioni/kross/rate-limit-trappole) per i dettagli |
Per errori non presenti in questa tabella, apri un ticket nel canale tecnico allegando il **log completo** della chiamata, non solo il messaggio di errore visibile nell'interfaccia. Includi: timestamp, `hotel_id`, endpoint chiamato, status code ricevuto e body della risposta. Senza questi dati, la diagnosi richiede molto più tempo.
**▷ Prompt Claude Code: Debug Kross** · incolla in Claude Code:
```text theme={null}
Contesto: in questa sessione di Claude Code NON hai il repo/codice caricato.
Per prima cosa apri il gateway `~/Projects/mattone-mcp-gateway` (log e proxy
Kross) e il repo `~/Projects/api-kross-mattone` (kross-api), e LEGGI le pagine
mattone-docs /troubleshooting/metodo e /integrazioni/kross/troubleshooting. Poi
procedi:
Applica il metodo di mattone-docs /troubleshooting/metodo a questo problema
Kross: [DESCRIVI IL SINTOMO, es. "test connessione rosso" / "occupato su date
libere per Casa X dal .. al .." / "errore sotto carico"]. LEGGI i log reali
prima di concludere: log del gateway mcp.mattone.co + risposta grezza Kross col
codice errore (11 combinazione, 16=429, 1010 Cloudflare). Isola: auth o parsing
disponibilità o rate-limit? Verifica la verità di riferimento con
run_custom_tool check-availability (property+date). Proponi il fix che spiega
cosa non va E come si risolve, e aggiorna questa tabella se lo scenario è nuovo.
```
Le 5 mosse
429 e errori noti