Il tuo software, le tue prenotazioni.

L'API di CocoBook dà a un channel manager, a un widget di prenotazione, a un export per la contabilità o a un tuo script l'accesso a prenotazioni, disponibilità e prezzi di una proprietà. JSON in entrata e in uscita, chiavi API con permessi, tentativi ripetuti sicuri, una descrizione OpenAPI.

REST · JSONChiavi per proprietà100 richieste/min

Per iniziare

In CocoBook apri Impostazioni → Sviluppatori e crea una chiave per la proprietà che vuoi collegare. Scegli i permessi che le servono; la chiave viene mostrata una sola volta. Poi verifica che funzioni:

Richiesta

curl https://api.cocobook.app/v1/me \
  -H "Authorization: Bearer cb_live_3fK9aBxQ7mNp2vLw8rTz4hJd6kYs1eCgU5oWnR0i"

Risposta · 200

{
  "key": {
    "id": "a1c3e5f7-9b2d-4e6f-8a0c-2d4f6b8a0c1e",
    "name": "Channel manager",
    "prefix": "cb_live_3fK9aB",
    "scopes": ["bookings:read", "bookings:write"],
    "created_at": "2026-10-14T09:12:00Z",
    "expires_at": "2027-10-14T09:12:00Z"
  },
  "property": {
    "id": "7d2f8a1c-9e4b-4d6a-8c3f-1b5e7a9d2c60",
    "name": "Sea House",
    "currency": "EUR",
    "location": {
      "country": "BG",
      "country_name": "Bulgaria",
      "region": "Burgas",
      "town": "Sozopol",
      "label": "Sozopol, Bulgaria"
    },
    "image_url": "https://cocobook.app/static/uploads/properties/7d2f8a1c.jpg",
    "created_at": "2026-03-02T15:40:11Z"
  }
}

expires_at è presente solo se alla chiave è stata data una scadenza, image_url solo se la proprietà ha un'immagine. Lo stesso oggetto property viene restituito da GET /property.

URL di base: https://api.cocobook.app/v1. La descrizione leggibile dalle macchine si trova su /v1/openapi.json — caricala in Postman, Insomnia o in un generatore di SDK.

Autenticazione e permessi

Ogni richiesta porta la chiave nell'header Authorization come bearer token (funziona anche X-API-Key: cb_live_…). Una chiave appartiene a una sola proprietà: non esiste un parametro per la proprietà, e tutto ciò che appartiene a un'altra proprietà risponde semplicemente 404. Solo proprietari e amministratori possono creare e revocare le chiavi; la revoca ha effetto immediato.

PermessoConsente
bookings:readElencare e leggere prenotazioni, disponibilità, preventivi
bookings:writeCreare, modificare e annullare prenotazioni; creare blocchi
property:readLeggere il profilo della proprietà e le sue unità
property:writeModificare il profilo della proprietà (nome, valuta, posizione)

Cosa ricevi quando la credenziale manca, è sbagliata o non ha il permesso necessario:

Nessuna chiave · 401

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="cocobook-api"

{"error": {"code": "missing_api_key", "message": "Send the API key as 'Authorization: Bearer cb_live_…'."}}

Chiave sconosciuta, revocata o scaduta · 401

{"error": {"code": "invalid_api_key", "message": "The API key is not valid."}}

Chiave senza il permesso · 403

{"error": {"code": "insufficient_scope", "message": "This key does not have the 'bookings:write' scope."}}

Il 401 è volutamente identico per una chiave revocata e per una mai esistita. GET /me non richiede alcun permesso, quindi è la chiamata giusta per un pulsante "verifica connessione".

Tratta una chiave come una password: usala dal tuo server, mai da una pagina web o da un'app mobile, e dai a ogni integrazione la propria chiave con i permessi minimi di cui ha bisogno.

Convenzioni

  • JSON, UTF-8. Invia Content-Type: application/json. I campi sconosciuti vengono rifiutati, così gli errori di battitura emergono come 400.
  • Gli id sono stringhe opache. Le date sono YYYY-MM-DD; check_out e ogni to sono esclusivi (dal 1 al 4 giugno sono tre notti). I timestamp sono RFC 3339 in UTC.
  • Gli elenchi arrivano come {"data": […], "page", "per_page", "total"}; per_page fino a 200.
  • Gli errori arrivano come {"error": {"code", "message", "details"}}. details indica i campi problematici.
  • I campi stringa opzionali (guest.email, guest.phone, notes, image_url, expires_at) vengono omessi dalle risposte quando sono vuoti, invece di essere inviati come null.
  • Niente viene messo in cache (Cache-Control: no-store). La versione è nel percorso; all'interno di v1 i campi vengono solo aggiunti.

Ogni risposta autenticata porta gli header del limite di richieste, qualunque sia lo stato:

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 37

Endpoint

EndpointPermessoCosa fa
GET/me—La chiave e la sua proprietà
GET/propertyproperty:readProfilo
PATCH/propertyproperty:writeModifica nome, valuta, posizione
GET/units, /units/{id}property:readUnità con capienza, prezzo base, colazione
GET/availabilitybookings:readPeriodi occupati per unità in un intervallo
GET/quotebookings:readCalcola il prezzo di un soggiorno
GET/bookings, /bookings/{id}bookings:readElenco con filtri, lettura di una singola prenotazione
POST/bookingsbookings:writeCrea una prenotazione o un blocco
PATCH/bookings/{id}bookings:writeModifica qualsiasi campo
DELETE/bookings/{id}bookings:writeAnnulla (anche POST …/cancel)

Prenotazioni

Gli esempi qui sotto seguono una prenotazione per tutta la sua vita: creata per un soggiorno a luglio, letta, prolungata di una notte e infine annullata. Usano tutti l'unità "Sea view" di Proprietà e unità.

Creare

Richiesta

curl -X POST https://api.cocobook.app/v1/bookings \
  -H "Authorization: Bearer cb_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-8812" \
  -d '{
    "unit_id": "b0e562a3-7c1e-4f0a-9d2b-5e8f1a6c3d47",
    "check_in": "2026-07-03",
    "check_out": "2026-07-06",
    "guest": {"name": "Ana Petrova", "email": "ana@example.com", "nationality": "BG"},
    "source": "booking_com",
    "breakfast_guests": 2,
    "deposit": 100
  }'

Obbligatori: unit_id, check_in, check_out, guest.name. status vale per default confirmed (oppure invia pending; le prenotazioni che il team accetta nel gestionale senza acconto tornano come deposit_pending, che blocca le date come confirmed); source vale per default direct ed è uno tra direct, airbnb, booking_com, agoda, referral. I soggiorni durano al massimo 365 notti. Se ometti price, il soggiorno viene prezzato in base alle stagioni della proprietà più la colazione, esattamente come farebbe /quote. La risposta è 201 con la prenotazione:

Risposta · 201

{
  "id": "e394b1d0-2a6f-4c8e-b7d3-91f0a5c2e468",
  "code": "B-4762",
  "unit": {"id": "b0e562a3-7c1e-4f0a-9d2b-5e8f1a6c3d47", "name": "Sea view"},
  "guest": {"name": "Ana Petrova", "email": "ana@example.com", "nationality": "BG"},
  "check_in": "2026-07-03",
  "check_out": "2026-07-06",
  "nights": 3,
  "status": "confirmed",
  "source": "booking_com",
  "price": 330,
  "deposit": 100,
  "currency": "EUR",
  "breakfast": {"guests": 2, "price": 30},
  "created_at": "2026-10-14T09:14:02Z",
  "updated_at": "2026-10-14T09:14:02Z"
}

price è il totale del soggiorno colazione inclusa (qui 300 per la camera più 30 per la colazione); breakfast.price è quella voce da sola. code è il riferimento breve che lo staff vede in CocoBook.

Se invii un campo che l'API non conosce, o un JSON malformato, il corpo viene rifiutato per intero:

Risposta · 400

{"error": {"code": "invalid_json", "message": "json: unknown field \"check_int\""}}

Un corpo ben formato con valori sbagliati indica tutti i campi problematici in una volta, così basta un solo giro per correggere un modulo:

Risposta · 400

{
  "error": {
    "code": "validation_error",
    "message": "One or more fields are invalid.",
    "details": {
      "check_out": "must be after check_in",
      "guest.email": "must be a valid email address",
      "source": "must be direct, airbnb, booking_com, agoda or referral"
    }
  }
}

L'unità deve essere libera per tutto il soggiorno. L'interfaccia del gestionale permette allo staff di creare prenotazioni sovrapposte e le segnala come conflitti; l'API invece le rifiuta: 409 unit_unavailable quando si sovrappone un'altra prenotazione attiva, 409 unit_blocked quando si sovrappone un blocco. details.conflicting_booking_ids indica quali:

Risposta · 409

{
  "error": {
    "code": "unit_unavailable",
    "message": "The unit already has a booking overlapping these dates.",
    "details": {"conflicting_booking_ids": ["0b1c7d9e-5f3a-4b2c-8e6d-7a9f1c3e5b20"]}
  }
}

Tentativi ripetuti sicuri

Invia un header Idempotency-Key (una qualsiasi stringa unica per il tentativo, fino a 255 caratteri) e un nuovo tentativo dopo un timeout restituirà la prenotazione creata la prima volta invece di un duplicato. Le chiavi vengono ricordate per 24 ore per ogni chiave API. La ripetizione risponde 200, non 201, ed è segnalata da un header:

Stessa richiesta di nuovo · 200

HTTP/1.1 200 OK
Idempotent-Replayed: true

{"id": "e394b1d0-2a6f-4c8e-b7d3-91f0a5c2e468", "code": "B-4762", …}

Viene confrontata solo la chiave, non il corpo, quindi non riutilizzare mai una chiave per un ordine diverso.

Blocchi

Imposta status su cleaning, owner o blocked per chiudere delle date senza un ospite. In questo caso guest.name è facoltativo e il blocco non viene mai prezzato, qualunque cosa tu invii:

Richiesta

POST /v1/bookings
{"unit_id": "b0e562a3-7c1e-4f0a-9d2b-5e8f1a6c3d47", "check_in": "2026-07-06", "check_out": "2026-07-07", "status": "cleaning"}

Risposta · 201

{
  "id": "c58a2f61-0d4e-4b9a-a3c7-6e1f8b2d9a05",
  "code": "BL-2210",
  "unit": {"id": "b0e562a3-7c1e-4f0a-9d2b-5e8f1a6c3d47", "name": "Sea view"},
  "guest": {},
  "check_in": "2026-07-06",
  "check_out": "2026-07-07",
  "nights": 1,
  "status": "cleaning",
  "source": "direct",
  "price": 0,
  "deposit": 0,
  "currency": "EUR",
  "breakfast": {"guests": 0, "price": 0},
  "created_at": "2026-10-14T09:15:30Z",
  "updated_at": "2026-10-14T09:15:30Z"
}

I blocchi ricevono un codice BL- e un guest vuoto. Il tuo team vede ogni scrittura via API nelle notifiche di CocoBook, con il nome della chiave.

Leggerne una

Richiesta

curl https://api.cocobook.app/v1/bookings/e394b1d0-2a6f-4c8e-b7d3-91f0a5c2e468 \
  -H "Authorization: Bearer cb_live_…"

Risponde 200 con lo stesso oggetto prenotazione della creazione. Un id di un'altra proprietà, un errore di battitura o una riga eliminata danno tutti la stessa risposta:

Risposta · 404

{"error": {"code": "not_found", "message": "No booking with that id."}}

Elencare e sincronizzare

GET /v1/bookings?from=2026-07-01&to=2026-08-01            # bookings overlapping July
GET /v1/bookings?status=confirmed,pending&unit_id=b0e5…
GET /v1/bookings?updated_since=2026-10-14T09:00:00Z        # poll this for changes
GET /v1/bookings?include_blocks=true&page=2&per_page=100

Risposta · 200

{
  "data": [
    {
      "id": "e394b1d0-2a6f-4c8e-b7d3-91f0a5c2e468",
      "code": "B-4762",
      "unit": {"id": "b0e562a3-7c1e-4f0a-9d2b-5e8f1a6c3d47", "name": "Sea view"},
      "guest": {"name": "Ana Petrova", "email": "ana@example.com", "nationality": "BG"},
      "check_in": "2026-07-03", "check_out": "2026-07-06", "nights": 3,
      "status": "confirmed", "source": "booking_com",
      "price": 330, "deposit": 100, "currency": "EUR",
      "breakfast": {"guests": 2, "price": 30},
      "created_at": "2026-10-14T09:14:02Z", "updated_at": "2026-10-14T09:14:02Z"
    },
    {
      "id": "f7a0c3e2-6b1d-4a8f-9c5e-3d2b7f1a8e94",
      "code": "B-1183",
      "unit": {"id": "4f7a9c21-3b8d-4e6a-a1c5-2d9e8b7f6a10", "name": "Garden studio"},
      "guest": {"name": "Tom Weber", "phone": "+49 170 1234567", "nationality": "DE"},
      "check_in": "2026-07-10", "check_out": "2026-07-17", "nights": 7,
      "status": "pending", "source": "direct",
      "price": 560, "deposit": 0, "currency": "EUR",
      "breakfast": {"guests": 0, "price": 0},
      "notes": "Arrives after 22:00",
      "created_at": "2026-10-02T18:03:44Z", "updated_at": "2026-10-02T18:03:44Z"
    }
  ],
  "page": 1,
  "per_page": 50,
  "total": 2
}

Ordinate per check-in. total conta tutte le corrispondenze su tutte le pagine; page parte da 1 e per_page vale per default 50. from e to selezionano le prenotazioni che si sovrappongono all'intervallo, non solo quelle che iniziano al suo interno. I blocchi sono esclusi a meno di include_blocks=true o di uno status che li nomini. Le prenotazioni annullate restano elencabili con status: cancelled.

Una prenotazione che lo staff ha creato sopra un'altra in CocoBook torna con status: conflict; puoi filtrare su questo stato, ma l'API non ne crea mai.

Per sincronizzare, ricorda l'ora dell'ultima interrogazione e chiedi tutto ciò che è stato modificato da allora; un annullamento o una modifica in CocoBook aggiorna updated_at, così compare:

GET /v1/bookings?updated_since=2026-10-14T09:00:00Z&include_blocks=true&per_page=200

Modificare

PATCH accetta gli stessi campi della creazione; cambiano solo quelli inviati. Spostare le date o l'unità ricontrolla le sovrapposizioni (le date della prenotazione stessa non contano mai) e, a meno che non venga inviato un price, ricalcola il prezzo del soggiorno. Ecco come prolungare di una notte il soggiorno di Ana:

Richiesta

curl -X PATCH https://api.cocobook.app/v1/bookings/e394b1d0-2a6f-4c8e-b7d3-91f0a5c2e468 \
  -H "Authorization: Bearer cb_live_…" \
  -H "Content-Type: application/json" \
  -d '{"check_out": "2026-07-07", "notes": "late arrival"}'

Risposta · 200

{
  "id": "e394b1d0-2a6f-4c8e-b7d3-91f0a5c2e468",
  "code": "B-4762",
  "unit": {"id": "b0e562a3-7c1e-4f0a-9d2b-5e8f1a6c3d47", "name": "Sea view"},
  "guest": {"name": "Ana Petrova", "email": "ana@example.com", "nationality": "BG"},
  "check_in": "2026-07-03",
  "check_out": "2026-07-07",
  "nights": 4,
  "status": "confirmed",
  "source": "booking_com",
  "price": 430,
  "deposit": 100,
  "currency": "EUR",
  "breakfast": {"guests": 2, "price": 40},
  "notes": "late arrival",
  "created_at": "2026-10-14T09:14:02Z",
  "updated_at": "2026-10-14T11:02:19Z"
}

Se il blocco per le pulizie di prima fosse ancora sul 6–7 luglio, la risposta sarebbe stata 409 unit_blocked. Invia "" per svuotare guest.email, guest.phone o notes; per mantenere il prezzo concordato mentre sposti le date, invialo insieme:

Richiesta

PATCH /v1/bookings/{id}
{"check_in": "2026-07-04", "check_out": "2026-07-08", "price": 400, "guest": {"email": ""}}

Annullare

Richiesta

curl -X DELETE https://api.cocobook.app/v1/bookings/e394b1d0-2a6f-4c8e-b7d3-91f0a5c2e468 \
  -H "Authorization: Bearer cb_live_…"

Risposta · 200

{
  "id": "e394b1d0-2a6f-4c8e-b7d3-91f0a5c2e468",
  "code": "B-4762",
  "status": "cancelled",
  "check_in": "2026-07-03",
  "check_out": "2026-07-07",
  "price": 430,
  "updated_at": "2026-10-15T08:30:00Z",
  …
}

POST /v1/bookings/{id}/cancel e PATCH con {"status": "cancelled"} fanno la stessa cosa. L'annullamento conserva la prenotazione con status: cancelled e libera le sue date e il parcheggio; annullare due volte non è un problema e risponde di nuovo 200.

Disponibilità e preventivi

Disponibilità

Richiesta

curl "https://api.cocobook.app/v1/availability?from=2026-07-01&to=2026-07-31&unit_id=b0e562a3-7c1e-4f0a-9d2b-5e8f1a6c3d47" \
  -H "Authorization: Bearer cb_live_…"

Risposta · 200

{
  "from": "2026-07-01",
  "to": "2026-07-31",
  "units": [
    {
      "unit": {"id": "b0e562a3-7c1e-4f0a-9d2b-5e8f1a6c3d47", "name": "Sea view"},
      "busy": [
        {"from": "2026-07-03", "to": "2026-07-06", "type": "booking", "status": "confirmed", "booking_id": "e394b1d0-2a6f-4c8e-b7d3-91f0a5c2e468"},
        {"from": "2026-07-06", "to": "2026-07-07", "type": "block", "status": "cleaning"},
        {"from": "2026-07-10", "to": "2026-07-14", "type": "external", "summary": "Airbnb (Not available)"}
      ]
    }
  ]
}

Tutto ciò che non è libero all'interno dell'intervallo, per unità: le prenotazioni attive (type: booking, con l'id per poterle leggere), i blocchi e gli eventi external importati dai feed iCal collegati dal proprietario (Airbnb, Booking.com). Ometti unit_id per ottenere tutte le unità; un'unità senza impegni ha "busy": []. Intervalli fino a 366 giorni. Tutto ciò che non è elencato è libero, comprese le prenotazioni annullate.

Entrambe le date sono obbligatorie e l'intervallo deve essere di almeno un giorno:

Risposta · 400

{"error": {"code": "validation_error", "message": "One or more fields are invalid.", "details": {"to": "range must be at most 366 days"}}}

Preventivo

Richiesta

curl "https://api.cocobook.app/v1/quote?unit_id=b0e562a3-7c1e-4f0a-9d2b-5e8f1a6c3d47&check_in=2026-07-03&check_out=2026-07-06&breakfast_guests=2" \
  -H "Authorization: Bearer cb_live_…"

Risposta · 200

{
  "unit": {"id": "b0e562a3-7c1e-4f0a-9d2b-5e8f1a6c3d47", "name": "Sea view"},
  "check_in": "2026-07-03",
  "check_out": "2026-07-06",
  "nights": 3,
  "currency": "EUR",
  "room": 300,
  "breakfast": {"guests": 2, "price": 30},
  "total": 330,
  "per_night": [
    {"date": "2026-07-03T00:00:00Z", "rate": 90,  "season": "Summer", "weekend": false},
    {"date": "2026-07-04T00:00:00Z", "rate": 105, "season": "Summer", "weekend": true},
    {"date": "2026-07-05T00:00:00Z", "rate": 105, "season": "Summer", "weekend": true}
  ]
}

Per ogni notte: la tariffa per unità della stagione, se impostata (con la sua variante weekend nei giorni di weekend della proprietà), altrimenti il prezzo base o weekend dell'unità moltiplicato per il moltiplicatore della stagione, altrimenti solo il prezzo base o weekend. season è assente nelle notti fuori da qualsiasi stagione. La colazione è ospiti × notti × la tariffa a persona dell'unità; un'unità senza colazione restituisce sempre {"guests": 0, "price": 0}. total è room più breakfast.price, e una prenotazione creata senza prezzo riceve esattamente questo totale.

Un preventivo non riserva nulla e non controlla la disponibilità. Il flusso tipico per un widget di prenotazione è /availability per mostrare le date libere, /quote per mostrare il prezzo, poi POST /bookings, trattando un 409 come "qualcuno è stato più veloce".

Proprietà e unità

Proprietà

Richiesta

curl -X PATCH https://api.cocobook.app/v1/property \
  -H "Authorization: Bearer cb_live_…" \
  -H "Content-Type: application/json" \
  -d '{"name": "Sea House", "currency": "EUR", "location": {"country": "BG", "region": "Burgas", "town": "Sozopol"}}'

Risposta · 200

{
  "id": "7d2f8a1c-9e4b-4d6a-8c3f-1b5e7a9d2c60",
  "name": "Sea House",
  "currency": "EUR",
  "location": {
    "country": "BG",
    "country_name": "Bulgaria",
    "region": "Burgas",
    "town": "Sozopol",
    "label": "Sozopol, Bulgaria"
  },
  "image_url": "https://cocobook.app/static/uploads/properties/7d2f8a1c.jpg",
  "created_at": "2026-03-02T15:40:11Z"
}

Cambiano solo i campi inviati, anche dentro location: {"location": {"town": "Chernomorets"}} mantiene paese e regione. GET /v1/property restituisce lo stesso oggetto. Valute: EUR USD GBP TRY BGN RON CHF; country è un codice ISO 3166-1 alpha-2; country_name e label sono derivati e di sola lettura. Una modifica al profilo aggiorna subito il sito per gli ospiti della proprietà e la sua scheda in Scopri gli alloggi. L'immagine non è modificabile tramite l'API.

Risposta · 400

{"error": {"code": "validation_error", "message": "One or more fields are invalid.", "details": {"currency": "must be one of EUR, USD, GBP, TRY, BGN, RON, CHF", "location.country": "must be an ISO 3166-1 alpha-2 code"}}}

Unità

Richiesta

curl https://api.cocobook.app/v1/units \
  -H "Authorization: Bearer cb_live_…"

Risposta · 200

{
  "data": [
    {
      "id": "b0e562a3-7c1e-4f0a-9d2b-5e8f1a6c3d47",
      "name": "Sea view",
      "type": "apartment",
      "capacity": 2,
      "floor": "2",
      "base_price": 75,
      "weekend_price": 90,
      "breakfast": true,
      "breakfast_price": 5
    },
    {
      "id": "4f7a9c21-3b8d-4e6a-a1c5-2d9e8b7f6a10",
      "name": "Garden studio",
      "type": "studio",
      "capacity": 3,
      "floor": "",
      "base_price": 80,
      "weekend_price": 0,
      "breakfast": false,
      "breakfast_price": 0
    }
  ]
}

Le unità sono di sola lettura tramite l'API e l'elenco non è paginato. base_price è la tariffa dei giorni feriali fuori stagione e weekend_price quella dei giorni di weekend della proprietà, dove 0 significa uguale a base_price. breakfast_price è a persona per notte, dove 0 significa inclusa. Le stagioni cambiano il costo reale di una notte, quindi usa /quote per un prezzo effettivo. GET /v1/units/{id} restituisce un singolo oggetto unità; type è uno tra studio, apartment, villa, room, loft.

Errori e limiti

CodiceHTTPSignificato
missing_api_key401Nessuna credenziale inviata
invalid_api_key401Chiave sconosciuta, revocata o scaduta
insufficient_scope403La chiave non ha il permesso
validation_error400Un campo è sbagliato — vedi details
invalid_json400Non è JSON, è vuoto, supera 64 KB o contiene campi sconosciuti
not_found404Nessuna risorsa del genere in questa proprietà
unit_unavailable409Si sovrappone un'altra prenotazione attiva
unit_blocked409Si sovrappone un blocco
rate_limited429Oltre 100 richieste in un minuto; attendi Retry-After
internal_error500Errore nostro; riprova più tardi

details è presente in validation_error (un messaggio per campo, i campi annidati come guest.email o location.country, i parametri della query con il loro nome) e nei due 409 (conflicting_booking_ids). Tutti gli altri errori hanno solo code e message.

Limite di richieste

Ogni chiave può effettuare 100 richieste al minuto. La finestra è il minuto dell'orologio, condiviso da tutti i nostri server, e si azzera all'inizio del minuto successivo invece che 60 secondi dopo la tua prima chiamata. Ogni risposta autenticata porta X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset (secondi mancanti all'azzeramento della finestra); contano solo le richieste con una chiave valida. La richiesta numero 101 in una finestra riceve:

Risposta · 429

HTTP/1.1 429 Too Many Requests
Retry-After: 23
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 23

{"error": {"code": "rate_limited", "message": "Too many requests; at most 100 per minute per key."}}

Regola il ritmo di un'importazione massiva osservando X-RateLimit-Remaining e, in caso di 429, attendi Retry-After secondi invece di riprovare subito.

Buone pratiche

  • Una chiave per integrazione, con il suo nome e solo i permessi che le servono. Revoca le chiavi che non usi più; dai una scadenza alle chiavi a breve termine.
  • Interroga updated_since invece di riscaricare tutto.
  • Tratta il 409 come un esito normale: rileggi /availability e proponi altre date.
  • Ripeti i 429 dopo Retry-After e i 5xx con backoff, sempre con un Idempotency-Key sulle creazioni.
  • Leggi solo i campi che ti servono e tollera quelli nuovi: dentro v1 le risposte possono guadagnare campi, mai perderli.

Domande o un caso d'uso che l'API non copre ancora? Scrivi a hello@cocobook.app.