Skip to main content
L’API di KrossBooking applica limiti di frequenza per struttura e presenta diversi comportamenti non ovvi che, se non conosciuti, producono errori silenziosi difficili da diagnosticare. Questa pagina documenta i limiti noti e le trappole più frequenti riscontrate durante l’integrazione con la piattaforma Mattone, leggila prima di configurare un nuovo studente o di fare debug su un flusso che non funziona come atteso.

​
Rate limit

I limiti di frequenza di KrossBooking sono applicati per struttura (cioè per hotel_id), non per account o per IP: 10 richieste/min · 300/h · 5.000/giorno (negoziabili). Se superi la soglia, Kross restituisce HTTP 429 (Too Many Requests), che è anche error_code 16, indistinguibile da una “lista vuota” se non controlli lo status. Il gateway mcp.mattone.co gestisce il backoff automatico in caso di 429, attendendo il tempo necessario prima di riprovare. Tuttavia, se i 429 si verificano in modo ricorrente, significa che la frequenza di polling configurata per quella struttura è troppo alta. In quel caso, riduci l’intervallo di polling nell’Admin della piattaforma o contatta il team tecnico per applicare il coalescing delle richieste parallele.
🔴 Perché il 429 è così pericoloso: se un check fa troppe chiamate, sotto burst scatta il 429 → il custom tool va in errore → l’agente Conduit ripiega sul calendario nativo (inaffidabile) → risponde “occupato” su date libere. È stata la vera root cause dei “non funziona” di Simone/studenti (test Botanique, 08/2026). Regola: minimizza le chiamate (1 dove basta 1), retry con backoff, mai far rispondere l’agente dal calendario nativo.

​
Trappole note

Alcuni endpoint di KrossBooking ignorano i filtri data inviati nella richiesta e restituiscono l’intero dataset disponibile, indipendentemente dal range specificato. Questo comportamento è silenzioso: la chiamata risponde con HTTP 200 ma i dati non sono filtrati.Come gestirlo: dopo ogni chiamata, valida sempre la risposta controllando il numero di record restituiti e verificando che le date siano coerenti con il range richiesto. Non assumere che il filtro sia stato applicato solo perché la chiamata ha avuto successo.
Per recuperare la disponibilità di una struttura, usa GET /v5/calendar/get-availability, non get-calendar. I due endpoint esistono entrambi ma restituiscono dati diversi: get-calendar fornisce una vista del calendario che non è adatta per la logica di disponibilità usata da Conduit.Come gestirlo: verifica sempre che il flusso di disponibilità punti all’endpoint corretto. Se Conduit riporta disponibilità incoerente, questo è il primo posto dove controllare.
Il path /apiv5 è l’interfaccia web della documentazione KrossBooking e restituisce HTML, non dati JSON. Qualsiasi chiamata effettuata a /apiv5/... otterrà una risposta HTML invece dei dati attesi, causando errori di parsing a valle.Come gestirlo: usa sempre il path /v5/... per tutte le chiamate API. Se ricevi una risposta inattesa con content-type text/html, controlla immediatamente il path usato.
Alcuni endpoint KrossBooking richiedono un header User-Agent che imiti un browser web. Le chiamate effettuate senza questo header, o con uno User-Agent da libreria HTTP standard, possono fallire con errori 403 o risposte vuote.Come gestirlo: il gateway mcp.mattone.co aggiunge automaticamente lo User-Agent corretto a tutte le richieste. Se stai testando direttamente un endpoint Kross fuori dal gateway (ad esempio con curl o Postman), aggiungi manualmente un header User-Agent di tipo browser per evitare questo problema.
Se una struttura genera molte richieste in parallelo, ad esempio durante picchi di traffico o quando più flussi Conduit si attivano contemporaneamente, il gateway può accumulare 429 anche con una frequenza di polling apparentemente ragionevole.Come gestirlo: il gateway supporta il coalescing delle richieste parallele verso lo stesso hotel_id: invece di inviare N richieste identiche, ne invia una sola e distribuisce la risposta a tutti i richiedenti. Questa funzionalità non è attiva di default, contatta il team tecnico per abilitarla per la struttura interessata.
Kross ignora i parametri che non riconosce, senza errore. Es.: passare status:"confirmed" a reservations/get-list non filtra, torna tutto. Il parametro corretto è cod_reservation_status:"CONF".Come gestirlo: usa i nomi di parametro esatti documentati e verifica il conteggio dei record. Non fidarti di un filtro solo perché la chiamata risponde 200.
calendar/get-availability non torna un calendario giorno-per-giorno libero/occupato, ma tanti intervalli sovrapposti (“soggiorno da date_from a date_to”) con un contatore available (0/total). Va espanso in giorni singoli (bloccato se available===0).Come gestirlo: è esattamente la logica che incapsula il custom tool check-availability, il nativo Conduit legge male questo formato. Endpoint corretto = calendar/get-availability (calendar/get-calendar non esiste).
Quando hai dubbi sul comportamento di un endpoint, testalo direttamente dalla console di debug del gateway prima di costruire logica sopra. Questo ti permette di vedere la risposta reale, inclusi header, status code e body, senza dover aspettare che un flusso in produzione fallisca.