Troubleshooting KrossBooking: sintomi, cause e soluzioni

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 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:

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.

Metodo troubleshooting

Le 5 mosse

Rate limit & trappole

429 e errori noti

PMS & CRM

Conduit AI

Numeri & WhatsApp (WABA)

Dati & Revenue

Pagamenti & Vendita diretta

Smart Lock

Troubleshooting KrossBooking: sintomi, cause e soluzioni

Tabella di diagnosi

Metodo troubleshooting

Rate limit & trappole

​Tabella di diagnosi

Metodo troubleshooting

Rate limit & trappole

Tabella di diagnosi