Votre logiciel, vos réservations.

L'API CocoBook donne à un channel manager, un widget de réservation, un export comptable ou votre propre script l'accès aux réservations, disponibilités et tarifs d'un logement. JSON en entrée comme en sortie, clés d'API avec droits, nouvelles tentatives sans risque, description OpenAPI.

REST · JSONUne clé par logement100 requêtes/min

Démarrage rapide

Dans CocoBook, ouvrez Paramètres → Développeur et créez une clé pour le logement à connecter. Choisissez les autorisations nécessaires ; la clé ne s'affiche qu'une seule fois. Vérifiez ensuite qu'elle fonctionne :

Requête

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

Réponse · 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 n'apparaît que si la clé a une date d'expiration, image_url uniquement si le logement a une photo. GET /property renvoie le même objet property.

URL de base : https://api.cocobook.app/v1. La description lisible par machine se trouve à l'adresse /v1/openapi.json : chargez-la dans Postman, Insomnia ou un générateur de SDK.

Authentification & droits

Chaque requête transmet la clé dans l'en-tête Authorization sous forme de jeton bearer (X-API-Key: cb_live_… fonctionne aussi). Une clé appartient à un seul logement : il n'y a pas de paramètre de logement, et tout ce qui appartient à un autre logement renvoie simplement 404. Seuls les propriétaires et les administrateurs peuvent créer et révoquer des clés ; la révocation est immédiate.

DroitAutorise
bookings:readLister et lire les réservations, les disponibilités, les devis
bookings:writeCréer, modifier et annuler des réservations ; créer des blocages
property:readLire la fiche du logement et ses unités
property:writeModifier la fiche du logement (nom, devise, emplacement)

Ce que vous recevez quand l'identifiant est absent, incorrect ou n'a pas le bon droit :

Pas de clé · 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_…'."}}

Clé inconnue, révoquée ou expirée · 401

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

Clé sans le droit requis · 403

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

Le 401 est volontairement identique pour une clé révoquée et pour une clé qui n'a jamais existé. GET /me ne demande aucun droit : c'est l'appel idéal pour un bouton « Tester la connexion ».

Traitez une clé comme un mot de passe : utilisez-la depuis votre serveur, jamais depuis une page web ou une application mobile, et donnez à chaque intégration sa propre clé avec le minimum de droits nécessaires.

Conventions

  • JSON, UTF-8. Envoyez Content-Type: application/json. Les champs inconnus sont rejetés, pour que les fautes de frappe ressortent en 400.
  • Les identifiants sont des chaînes opaques. Les dates sont au format YYYY-MM-DD ; check_out et chaque to sont exclusifs (du 1er au 4 juin, cela fait trois nuits). Les horodatages sont en RFC 3339, en UTC.
  • Les listes ont la forme {"data": […], "page", "per_page", "total"} ; per_page va jusqu'à 200.
  • Les erreurs ont la forme {"error": {"code", "message", "details"}}. details indique les champs en cause.
  • Les champs texte facultatifs (guest.email, guest.phone, notes, image_url, expires_at) sont omis des réponses lorsqu'ils sont vides, au lieu d'être envoyés à null.
  • Rien n'est mis en cache (Cache-Control: no-store). La version figure dans le chemin ; au sein de v1, des champs peuvent seulement être ajoutés.

Chaque réponse authentifiée contient les en-têtes de limite de débit, quel que soit le statut :

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

Points d'accès

Point d'accèsDroitRôle
GET/me—La clé et son logement
GET/propertyproperty:readFiche du logement
PATCH/propertyproperty:writeModifier le nom, la devise, l'emplacement
GET/units, /units/{id}property:readUnités avec capacité, prix de base, petit-déjeuner
GET/availabilitybookings:readPériodes occupées par unité sur une fenêtre de dates
GET/quotebookings:readCalculer le prix d'un séjour
GET/bookings, /bookings/{id}bookings:readLister avec des filtres, lire une réservation
POST/bookingsbookings:writeCréer une réservation ou un blocage
PATCH/bookings/{id}bookings:writeModifier n'importe quel champ
DELETE/bookings/{id}bookings:writeAnnuler (ou POST …/cancel)

Réservations

Les exemples ci-dessous suivent une réservation tout au long de sa vie : créée pour un séjour en juillet, lue, prolongée d'une nuit, puis annulée. Ils utilisent tous l'unité « Sea view » de la section Logement & unités.

Créer

Requête

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
  }'

Obligatoires : unit_id, check_in, check_out, guest.name. status vaut confirmed par défaut (ou envoyez pending ; les réservations que l'équipe accepte dans l'interface de gestion sans acompte reviennent en deposit_pending, qui bloque les dates comme confirmed) ; source vaut direct par défaut et peut être direct, airbnb, booking_com, agoda ou referral. Un séjour dure au maximum 365 nuits. Sans price, le séjour est calculé d'après les saisons du logement plus le petit-déjeuner, exactement comme le ferait /quote. La réponse est un 201 avec la réservation :

Réponse · 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 est le total du séjour, petit-déjeuner compris (ici 300 pour l'hébergement plus 30 pour le petit-déjeuner) ; breakfast.price correspond à cette ligne seule. code est la référence courte que l'équipe voit dans CocoBook.

Si vous envoyez un champ que l'API ne connaît pas, ou un JSON mal formé, le corps est rejeté en entier :

Réponse · 400

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

Un corps bien formé mais avec des valeurs incorrectes indique tous les champs en cause d'un coup : un seul aller-retour suffit pour corriger un formulaire.

Réponse · 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é doit être libre pendant tout le séjour. L'interface de gestion permet à l'équipe de créer des réservations qui se chevauchent et les signale comme conflits ; l'API, elle, les refuse : 409 unit_unavailable si une autre réservation active chevauche les dates, 409 unit_blocked si c'est un blocage. details.conflicting_booking_ids indique lesquelles :

Réponse · 409

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

Nouvelles tentatives sans risque

Envoyez un en-tête Idempotency-Key (n'importe quelle chaîne propre à la tentative, jusqu'à 255 caractères) : une nouvelle tentative après un délai dépassé renvoie la réservation créée la première fois au lieu d'un doublon. Les clés sont conservées 24 heures par clé d'API. La réponse rejouée est un 200, pas un 201, et elle est signalée par un en-tête :

Même requête renvoyée · 200

HTTP/1.1 200 OK
Idempotent-Replayed: true

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

Seule la clé est comparée, pas le corps : ne réutilisez donc jamais une clé pour une autre commande.

Blocages

Mettez status à cleaning, owner ou blocked pour fermer des dates sans voyageur. guest.name devient alors facultatif et le blocage n'est jamais facturé, quoi que vous envoyiez :

Requête

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

Réponse · 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"
}

Les blocages reçoivent un code BL- et un guest vide. Votre équipe voit chaque écriture faite via l'API dans les notifications de CocoBook, sous le nom de la clé.

Lire une réservation

Requête

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

Répond 200 avec le même objet réservation qu'à la création. Un identifiant d'un autre logement, une faute de frappe ou une ligne supprimée donnent tous la même réponse :

Réponse · 404

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

Lister et synchroniser

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

Réponse · 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
}

Tri par date d'arrivée. total compte tous les résultats sur l'ensemble des pages ; page commence à 1 et per_page vaut 50 par défaut. from et to sélectionnent les réservations qui chevauchent la fenêtre, pas seulement celles qui y commencent. Les blocages sont exclus sauf avec include_blocks=true ou si status les nomme. Les réservations annulées restent listables avec status: cancelled.

Une réservation que l'équipe a créée par-dessus une autre dans CocoBook revient avec status: conflict ; vous pouvez filtrer dessus, mais l'API n'en crée jamais.

Pour une synchronisation, retenez l'heure de votre dernière interrogation et demandez tout ce qui a changé depuis ; une annulation ou une modification dans CocoBook met à jour updated_at, elle apparaît donc :

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

Modifier

PATCH accepte les mêmes champs que la création ; seuls ceux envoyés changent. Déplacer les dates ou l'unité revérifie les chevauchements (les dates de la réservation elle-même ne comptent jamais) et, sauf si un price est envoyé, recalcule le prix du séjour. Prolonger d'une nuit le séjour d'Ana :

Requête

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"}'

Réponse · 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"
}

Si le blocage ménage vu plus haut occupait encore le 6–7 juillet, la réponse aurait été 409 unit_blocked. Envoyez "" pour vider guest.email, guest.phone ou notes ; pour garder le prix négocié en déplaçant les dates, envoyez-le aussi :

Requête

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

Annuler

Requête

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

Réponse · 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 et PATCH avec {"status": "cancelled"} font la même chose. L'annulation conserve la réservation avec status: cancelled et libère ses dates et son parking ; annuler deux fois ne pose aucun problème et renvoie de nouveau 200.

Disponibilités & devis

Disponibilités

Requête

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_…"

Réponse · 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)"}
      ]
    }
  ]
}

Tout ce qui n'est pas libre dans la fenêtre, par unité : réservations actives (type: booking, avec l'identifiant pour pouvoir la lire), blocages, et événements external importés des flux iCal connectés par le propriétaire (Airbnb, Booking.com). Omettez unit_id pour obtenir toutes les unités ; une unité sans rien de prévu a "busy": []. Fenêtres de 366 jours au maximum. Tout ce qui n'est pas listé est libre, y compris les réservations annulées.

Les deux dates sont obligatoires et la fenêtre doit couvrir au moins un jour :

Réponse · 400

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

Devis

Requête

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_…"

Réponse · 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}
  ]
}

Pour chaque nuit : le tarif de la saison pour l'unité s'il est défini (sa variante week-end les jours de week-end du logement), sinon le prix de base ou de week-end de l'unité multiplié par le coefficient de la saison, sinon le prix de base ou de week-end seul. season est absent pour les nuits hors saison. Le petit-déjeuner vaut voyageurs × nuits × tarif par personne de l'unité ; une unité sans petit-déjeuner renvoie toujours {"guests": 0, "price": 0}. total correspond à room plus breakfast.price, et une réservation créée sans prix reçoit exactement ce total.

Un devis ne réserve rien et ne vérifie pas les disponibilités. Le parcours habituel d'un widget de réservation : /availability pour afficher les dates libres, /quote pour afficher le prix, puis POST /bookings, en traitant un 409 comme « quelqu'un a été plus rapide ».

Logement & unités

Logement

Requête

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"}}'

Réponse · 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"
}

Seuls les champs envoyés changent, y compris dans location : {"location": {"town": "Chernomorets"}} conserve donc le pays et la région. GET /v1/property renvoie le même objet. Devises : EUR USD GBP TRY BGN RON CHF ; country est un code ISO 3166-1 alpha-2 ; country_name et label sont calculés et en lecture seule. Toute modification de la fiche met aussitôt à jour le site pour les voyageurs du logement et son annonce dans Découvrir les séjours. La photo n'est pas modifiable via l'API.

Réponse · 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és

Requête

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

Réponse · 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
    }
  ]
}

Les unités sont en lecture seule via l'API et la liste n'est pas paginée. base_price est le tarif de semaine hors saison et weekend_price le tarif des jours de week-end du logement, 0 signifiant identique à base_price. breakfast_price s'entend par personne et par nuit, 0 signifiant inclus. Les saisons modifient le prix réel d'une nuit : utilisez /quote pour obtenir un vrai prix. GET /v1/units/{id} renvoie un seul objet unité ; type vaut studio, apartment, villa, room ou loft.

Erreurs & limites

CodeHTTPSignification
missing_api_key401Aucun identifiant envoyé
invalid_api_key401Clé inconnue, révoquée ou expirée
insufficient_scope403La clé n'a pas le droit requis
validation_error400Un champ est incorrect : voir details
invalid_json400Pas du JSON, vide, plus de 64 Ko, ou champs inconnus
not_found404Cette ressource n'existe pas pour ce logement
unit_unavailable409Une autre réservation active chevauche les dates
unit_blocked409Un blocage chevauche les dates
rate_limited429Plus de 100 requêtes en une minute ; attendez Retry-After
internal_error500Erreur de notre côté ; réessayez plus tard

details est présent pour validation_error (un message par champ, les champs imbriqués sous la forme guest.email ou location.country, les paramètres de requête sous leur nom) et pour les deux 409 (conflicting_booking_ids). Toutes les autres erreurs contiennent seulement code et message.

Limite de débit

Chaque clé peut effectuer 100 requêtes par minute. La fenêtre correspond à la minute d'horloge, partagée par tous nos serveurs, et elle se réinitialise au début de la minute suivante plutôt que 60 secondes après votre premier appel. Chaque réponse authentifiée contient X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset (secondes avant la réinitialisation) ; seules les requêtes avec une clé valide sont comptées. La 101e requête d'une fenêtre reçoit :

Réponse · 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."}}

Pour un import en masse, réglez le rythme en surveillant X-RateLimit-Remaining, et après un 429, attendez Retry-After secondes au lieu de réessayer aussitôt.

Bonnes pratiques

  • Une clé par intégration, nommée d'après elle, avec uniquement les droits nécessaires. Révoquez les clés que vous n'utilisez plus ; donnez une date d'expiration aux clés temporaires.
  • Interrogez updated_since plutôt que de tout récupérer à nouveau.
  • Traitez un 409 comme un résultat normal : relisez /availability et proposez d'autres dates.
  • Réessayez les 429 après Retry-After et les 5xx avec un délai croissant, toujours avec un Idempotency-Key pour les créations.
  • Ne lisez que les champs utiles et acceptez les nouveaux : au sein de v1, les réponses gagnent des champs, sans jamais en perdre.

Une question, ou un cas d'usage que l'API ne couvre pas encore ? Écrivez à hello@cocobook.app.