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.
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.
| Droit | Autorise |
|---|---|
bookings:read | Lister et lire les réservations, les disponibilités, les devis |
bookings:write | Créer, modifier et annuler des réservations ; créer des blocages |
property:read | Lire la fiche du logement et ses unités |
property:write | Modifier 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 en400. - Les identifiants sont des chaînes opaques. Les dates sont au format
YYYY-MM-DD;check_outet chaquetosont 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_pageva jusqu'à 200. - Les erreurs ont la forme
{"error": {"code", "message", "details"}}.detailsindique 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 dev1, 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ès | Droit | Rôle |
|---|---|---|
GET/me | — | La clé et son logement |
GET/property | property:read | Fiche du logement |
PATCH/property | property:write | Modifier le nom, la devise, l'emplacement |
GET/units, /units/{id} | property:read | Unités avec capacité, prix de base, petit-déjeuner |
GET/availability | bookings:read | Périodes occupées par unité sur une fenêtre de dates |
GET/quote | bookings:read | Calculer le prix d'un séjour |
GET/bookings, /bookings/{id} | bookings:read | Lister avec des filtres, lire une réservation |
POST/bookings | bookings:write | Créer une réservation ou un blocage |
PATCH/bookings/{id} | bookings:write | Modifier n'importe quel champ |
DELETE/bookings/{id} | bookings:write | Annuler (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
| Code | HTTP | Signification |
|---|---|---|
missing_api_key | 401 | Aucun identifiant envoyé |
invalid_api_key | 401 | Clé inconnue, révoquée ou expirée |
insufficient_scope | 403 | La clé n'a pas le droit requis |
validation_error | 400 | Un champ est incorrect : voir details |
invalid_json | 400 | Pas du JSON, vide, plus de 64 Ko, ou champs inconnus |
not_found | 404 | Cette ressource n'existe pas pour ce logement |
unit_unavailable | 409 | Une autre réservation active chevauche les dates |
unit_blocked | 409 | Un blocage chevauche les dates |
rate_limited | 429 | Plus de 100 requêtes en une minute ; attendez Retry-After |
internal_error | 500 | Erreur 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_sinceplutôt que de tout récupérer à nouveau. - Traitez un
409comme un résultat normal : relisez/availabilityet proposez d'autres dates. - Réessayez les
429aprèsRetry-Afteret les5xxavec un délai croissant, toujours avec unIdempotency-Keypour 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.