> ## 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.
# KrossBooking: rate limit, trappole e comportamenti non ovvi
> Limiti di frequenza per struttura sull'API Kross e cinque comportamenti non ovvi che producono errori silenziosi nell'integrazione Mattone.
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.