Deine Software, deine Buchungen.
Die CocoBook-API gibt einem Channel-Manager, einem Buchungs-Widget, einem Buchhaltungsexport oder deinem eigenen Skript Zugriff auf die Buchungen, die Verfügbarkeit und die Preise einer Unterkunft. JSON rein und raus, API-Schlüssel mit Berechtigungen, sichere Wiederholungen und eine OpenAPI-Beschreibung.
Schnellstart
Öffne in CocoBook Einstellungen → Entwickler und erstelle einen Schlüssel für die Unterkunft, die du anbinden willst. Wähle die Berechtigungen, die er braucht; der Schlüssel wird nur einmal angezeigt. Prüfe danach, ob er funktioniert:
Anfrage
curl https://api.cocobook.app/v1/me \
-H "Authorization: Bearer cb_live_3fK9aBxQ7mNp2vLw8rTz4hJd6kYs1eCgU5oWnR0i"
Antwort · 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 erscheint nur, wenn der Schlüssel ein Ablaufdatum hat, und image_url nur, wenn die Unterkunft ein Bild hat. Dasselbe property-Objekt liefert auch GET /property.
Basis-URL: https://api.cocobook.app/v1. Die maschinenlesbare Beschreibung liegt unter /v1/openapi.json – lade sie in Postman, Insomnia oder einen SDK-Generator.
Authentifizierung & Berechtigungen
Jede Anfrage trägt den Schlüssel im Authorization-Header als Bearer-Token (X-API-Key: cb_live_… geht auch). Ein Schlüssel gehört zu genau einer Unterkunft: Es gibt keinen Unterkunftsparameter, und alles aus einer anderen Unterkunft liefert einfach 404. Nur Eigentümer und Administratoren können Schlüssel erstellen und widerrufen; ein Widerruf wirkt sofort.
| Berechtigung | Erlaubt |
|---|---|
bookings:read | Buchungen, Verfügbarkeit und Preisangebote auflisten und lesen |
bookings:write | Buchungen anlegen, ändern und stornieren; Sperren anlegen |
property:read | Das Profil der Unterkunft und ihre Einheiten lesen |
property:write | Das Profil der Unterkunft ändern (Name, Währung, Standort) |
Das bekommst du zurück, wenn die Zugangsdaten fehlen, falsch sind oder die Berechtigung fehlt:
Kein Schlüssel · 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_…'."}}
Unbekannter, widerrufener oder abgelaufener Schlüssel · 401
{"error": {"code": "invalid_api_key", "message": "The API key is not valid."}}
Schlüssel ohne Berechtigung · 403
{"error": {"code": "insufficient_scope", "message": "This key does not have the 'bookings:write' scope."}}
Der 401 ist bewusst identisch für einen widerrufenen Schlüssel und einen, den es nie gab. GET /me braucht keine Berechtigung und ist damit der richtige Aufruf für eine „Verbindung testen“-Schaltfläche.
Behandle einen Schlüssel wie ein Passwort: Nutze ihn von deinem Server aus, nie aus einer Webseite oder einer mobilen App, und gib jeder Integration einen eigenen Schlüssel mit den minimal nötigen Berechtigungen.
Konventionen
- JSON, UTF-8. Sende
Content-Type: application/json. Unbekannte Felder werden abgelehnt, damit Tippfehler als400auffallen. - IDs sind undurchsichtige Strings. Datumsangaben sind
YYYY-MM-DD;check_outund jedestosind exklusiv (1. bis 4. Juni sind drei Nächte). Zeitstempel sind RFC 3339 in UTC. - Listen kommen als
{"data": […], "page", "per_page", "total"};per_pagebis 200. - Fehler kommen als
{"error": {"code", "message", "details"}}.detailsnennt die fehlerhaften Felder. - Optionale Textfelder (
guest.email,guest.phone,notes,image_url,expires_at) werden in Antworten weggelassen, wenn sie leer sind, statt alsnullgesendet zu werden. - Nichts wird gecacht (
Cache-Control: no-store). Die Version steht im Pfad; innerhalb vonv1kommen nur Felder hinzu.
Jede authentifizierte Antwort enthält die Rate-Limit-Header, unabhängig vom Status:
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
Endpunkte
| Endpunkt | Berechtigung | Funktion |
|---|---|---|
GET/me | — | Der Schlüssel und seine Unterkunft |
GET/property | property:read | Profil |
PATCH/property | property:write | Name, Währung und Standort ändern |
GET/units, /units/{id} | property:read | Einheiten mit Kapazität, Grundpreis und Frühstück |
GET/availability | bookings:read | Belegte Zeiträume pro Einheit in einem Zeitraum |
GET/quote | bookings:read | Preis eines Aufenthalts berechnen |
GET/bookings, /bookings/{id} | bookings:read | Mit Filtern auflisten, einzeln lesen |
POST/bookings | bookings:write | Buchung oder Sperre anlegen |
PATCH/bookings/{id} | bookings:write | Beliebige Felder ändern |
DELETE/bookings/{id} | bookings:write | Stornieren (auch POST …/cancel) |
Buchungen
Die folgenden Beispiele begleiten eine Buchung durch ihr ganzes Leben: Sie wird für einen Aufenthalt im Juli angelegt, gelesen, um eine Nacht verlängert und dann storniert. Alle nutzen die Einheit „Sea view“ aus Unterkunft & Einheiten.
Anlegen
Anfrage
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
}'
Pflichtfelder: unit_id, check_in, check_out, guest.name. status ist standardmäßig confirmed (oder sende pending; Buchungen, die das Team im Verwaltungsbereich ohne Anzahlung annimmt, kommen als deposit_pending zurück, das die Tage genauso blockiert wie confirmed); source ist standardmäßig direct und kann direct, airbnb, booking_com, agoda oder referral sein. Aufenthalte haben höchstens 365 Nächte. Lässt du price weg, wird der Aufenthalt aus den Saisons der Unterkunft plus Frühstück berechnet – genau so, wie es /quote tun würde. Die Antwort ist 201 mit der Buchung:
Antwort · 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 ist der Gesamtpreis des Aufenthalts inklusive Frühstück (hier 300 für das Zimmer plus 30 für das Frühstück); breakfast.price ist diese Position einzeln. code ist die kurze Referenz, die das Team in CocoBook sieht.
Sendest du ein Feld, das die API nicht kennt, oder fehlerhaftes JSON, wird der gesamte Body abgelehnt:
Antwort · 400
{"error": {"code": "invalid_json", "message": "json: unknown field \"check_int\""}}
Ein gültiger Body mit falschen Werten nennt alle fehlerhaften Felder auf einmal – ein einziger Durchlauf reicht also, um ein Formular zu korrigieren:
Antwort · 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"
}
}
}
Die Einheit muss für den gesamten Aufenthalt frei sein. Die Verwaltungsoberfläche lässt das Team überlappende Buchungen anlegen und markiert sie als Konflikte; die API lehnt sie dagegen ab: 409 unit_unavailable, wenn sich eine andere aktive Buchung überschneidet, und 409 unit_blocked, wenn sich eine Sperre überschneidet. details.conflicting_booking_ids nennt die betroffenen:
Antwort · 409
{
"error": {
"code": "unit_unavailable",
"message": "The unit already has a booking overlapping these dates.",
"details": {"conflicting_booking_ids": ["0b1c7d9e-5f3a-4b2c-8e6d-7a9f1c3e5b20"]}
}
}
Sichere Wiederholungen
Sende einen Idempotency-Key-Header (ein beliebiger, für diesen Versuch eindeutiger String mit bis zu 255 Zeichen), und eine Wiederholung nach einem Timeout liefert die beim ersten Mal angelegte Buchung statt eines Duplikats. Die Schlüssel werden pro API-Schlüssel 24 Stunden lang gespeichert. Die Wiederholung liefert 200, nicht 201, und ist mit einem Header gekennzeichnet:
Dieselbe Anfrage noch einmal · 200
HTTP/1.1 200 OK
Idempotent-Replayed: true
{"id": "e394b1d0-2a6f-4c8e-b7d3-91f0a5c2e468", "code": "B-4762", …}
Verglichen wird nur der Schlüssel, nicht der Body – verwende einen Schlüssel also nie für eine andere Bestellung wieder.
Sperren
Setze status auf cleaning, owner oder blocked, um Tage ohne Gast zu sperren. Dann ist guest.name optional, und eine Sperre hat nie einen Preis, egal was du sendest:
Anfrage
POST /v1/bookings
{"unit_id": "b0e562a3-7c1e-4f0a-9d2b-5e8f1a6c3d47", "check_in": "2026-07-06", "check_out": "2026-07-07", "status": "cleaning"}
Antwort · 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"
}
Sperren bekommen einen BL--Code und ein leeres guest. Dein Team sieht jeden Schreibzugriff über die API in den CocoBook-Benachrichtigungen, mit dem Namen des Schlüssels.
Einzeln lesen
Anfrage
curl https://api.cocobook.app/v1/bookings/e394b1d0-2a6f-4c8e-b7d3-91f0a5c2e468 \
-H "Authorization: Bearer cb_live_…"
Antwortet mit 200 und demselben Buchungsobjekt wie beim Anlegen. Eine ID aus einer anderen Unterkunft, ein Tippfehler oder ein gelöschter Eintrag führen zur selben Antwort:
Antwort · 404
{"error": {"code": "not_found", "message": "No booking with that id."}}
Auflisten & synchronisieren
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
Antwort · 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
}
Sortiert nach Anreisedatum. total zählt alle Treffer über alle Seiten; page beginnt bei 1, und per_page ist standardmäßig 50. from und to wählen Buchungen, die sich mit dem Zeitraum überschneiden, nicht nur solche, die darin beginnen. Sperren werden weggelassen, außer du setzt include_blocks=true oder status nennt sie. Stornierte Buchungen bleiben mit status: cancelled in der Liste.
Eine Buchung, die das Team in CocoBook über eine andere gelegt hat, kommt mit status: conflict zurück; du kannst nach diesem Status filtern, aber die API legt nie selbst eine an.
Zum Synchronisieren speicherst du den Zeitpunkt deiner letzten Abfrage und fragst alles ab, was sich seitdem geändert hat; eine Stornierung oder Bearbeitung in CocoBook aktualisiert updated_at, taucht also auf:
GET /v1/bookings?updated_since=2026-10-14T09:00:00Z&include_blocks=true&per_page=200
Ändern
PATCH akzeptiert dieselben Felder wie das Anlegen; nur die gesendeten ändern sich. Werden Daten oder Einheit verschoben, werden Überschneidungen erneut geprüft (die eigenen Tage der Buchung zählen nie mit), und sofern du keinen price sendest, wird der Preis des Aufenthalts neu berechnet. Anas Aufenthalt um eine Nacht verlängern:
Anfrage
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"}'
Antwort · 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"
}
Würde die Reinigungssperre von vorhin noch den 6.–7. Juli belegen, wäre die Antwort 409 unit_blocked gewesen. Sende "", um guest.email, guest.phone oder notes zu leeren; um beim Verschieben der Daten den ausgehandelten Preis zu behalten, sende ihn mit:
Anfrage
PATCH /v1/bookings/{id}
{"check_in": "2026-07-04", "check_out": "2026-07-08", "price": 400, "guest": {"email": ""}}
Stornieren
Anfrage
curl -X DELETE https://api.cocobook.app/v1/bookings/e394b1d0-2a6f-4c8e-b7d3-91f0a5c2e468 \
-H "Authorization: Bearer cb_live_…"
Antwort · 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 und PATCH mit {"status": "cancelled"} machen dasselbe. Beim Stornieren bleibt die Buchung mit status: cancelled erhalten, und ihre Tage und ihr Parkplatz werden frei; zweimal stornieren ist kein Problem und liefert wieder 200.
Verfügbarkeit & Preisangebote
Verfügbarkeit
Anfrage
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_…"
Antwort · 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)"}
]
}
]
}
Alles, was im Zeitraum nicht frei ist, pro Einheit: aktive Buchungen (type: booking, mit der ID, damit du sie lesen kannst), Sperren und external-Ereignisse aus den iCal-Feeds, die der Eigentümer verbunden hat (Airbnb, Booking.com). Lass unit_id weg, um alle Einheiten zu bekommen; eine Einheit ohne Belegung hat "busy": []. Zeiträume bis 366 Tage. Alles, was nicht aufgeführt ist, ist frei – auch stornierte Buchungen.
Beide Daten sind Pflicht, und der Zeitraum muss mindestens einen Tag lang sein:
Antwort · 400
{"error": {"code": "validation_error", "message": "One or more fields are invalid.", "details": {"to": "range must be at most 366 days"}}}
Preisangebot
Anfrage
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_…"
Antwort · 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}
]
}
Pro Nacht: der Einheitspreis der Saison, falls festgelegt (an den Wochenendtagen der Unterkunft dessen Wochenendvariante); sonst der Grund- oder Wochenendpreis der Einheit mal dem Multiplikator der Saison; und sonst einfach der Grund- oder Wochenendpreis. season fehlt bei Nächten, die in keine Saison fallen. Frühstück ist Gäste × Nächte × der Preis pro Person der Einheit; eine Einheit ohne Frühstück liefert immer {"guests": 0, "price": 0}. total ist room plus breakfast.price, und eine ohne Preis angelegte Buchung bekommt genau diese Summe.
Ein Preisangebot reserviert nichts und prüft keine Verfügbarkeit. Der übliche Ablauf eines Buchungs-Widgets ist /availability, um freie Tage zu zeigen, /quote, um den Preis zu zeigen, dann POST /bookings – und ein 409 als „jemand war schneller“ zu behandeln.
Unterkunft & Einheiten
Unterkunft
Anfrage
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"}}'
Antwort · 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"
}
Nur gesendete Felder ändern sich, auch innerhalb von location – {"location": {"town": "Chernomorets"}} behält also Land und Region. GET /v1/property liefert dasselbe Objekt. Währungen: EUR USD GBP TRY BGN RON CHF; country ist ein ISO-3166-1-Alpha-2-Code; country_name und label werden abgeleitet und sind schreibgeschützt. Eine Profiländerung aktualisiert sofort die Gäste-Website der Unterkunft und ihren Eintrag unter „Unterkünfte entdecken“. Das Bild lässt sich über die API nicht bearbeiten.
Antwort · 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"}}}
Einheiten
Anfrage
curl https://api.cocobook.app/v1/units \
-H "Authorization: Bearer cb_live_…"
Antwort · 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
}
]
}
Einheiten sind in der API schreibgeschützt, und die Liste ist nicht paginiert. base_price ist der Preis unter der Woche außerhalb der Saison und weekend_price der Preis an den Wochenendtagen der Unterkunft; 0 bedeutet dasselbe wie base_price. breakfast_price gilt pro Person und Nacht; 0 bedeutet inklusive. Saisons ändern, was eine Nacht tatsächlich kostet – nutze also /quote für einen echten Preis. GET /v1/units/{id} liefert ein einzelnes Einheitsobjekt; type kann studio, apartment, villa, room oder loft sein.
Fehler & Limits
| Code | HTTP | Bedeutung |
|---|---|---|
missing_api_key | 401 | Keine Zugangsdaten gesendet |
invalid_api_key | 401 | Unbekannter, widerrufener oder abgelaufener Schlüssel |
insufficient_scope | 403 | Dem Schlüssel fehlt die Berechtigung |
validation_error | 400 | Ein Feld ist ungültig – siehe details |
invalid_json | 400 | Kein JSON, leer, größer als 64 KB oder mit unbekannten Feldern |
not_found | 404 | Die Ressource existiert in dieser Unterkunft nicht |
unit_unavailable | 409 | Eine andere aktive Buchung überschneidet sich |
unit_blocked | 409 | Eine Sperre überschneidet sich |
rate_limited | 429 | Mehr als 100 Anfragen in einer Minute – warte Retry-After ab |
internal_error | 500 | Unser Fehler – versuch es später noch einmal |
details erscheint bei validation_error (eine Meldung pro Feld, verschachtelte Felder wie guest.email oder location.country und Abfrageparameter unter ihrem Namen) und bei den beiden 409 (conflicting_booking_ids). Jeder andere Fehler enthält nur code und message.
Rate-Limit
Jeder Schlüssel darf 100 Anfragen pro Minute stellen. Das Zeitfenster ist die Uhrminute, geteilt über alle unsere Server, und setzt sich zu Beginn der nächsten Minute zurück – nicht 60 Sekunden nach deinem ersten Aufruf. Jede authentifizierte Antwort enthält X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset (Sekunden bis zum Zurücksetzen des Fensters); es zählen nur Anfragen mit gültigem Schlüssel. Die 101. Anfrage in einem Fenster bekommt:
Antwort · 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."}}
Drossle einen Massenimport anhand von X-RateLimit-Remaining und warte bei einem 429 Retry-After Sekunden, statt sofort erneut zu senden.
Bewährte Praktiken
- Ein Schlüssel pro Integration, benannt und nur mit den Berechtigungen, die sie braucht. Widerrufe Schlüssel, die du nicht mehr nutzt; gib temporären Schlüsseln ein Ablaufdatum.
- Frag
updated_sinceab, statt alles neu herunterzuladen. - Behandle ein
409als normales Ergebnis: Lies/availabilityerneut und biete andere Daten an. - Wiederhole
429nachRetry-Afterund5xxmit zunehmender Wartezeit – beim Anlegen immer mit einemIdempotency-Key. - Lies nur die Felder, die du brauchst, und toleriere neue: Innerhalb von
v1bekommen Antworten Felder dazu, verlieren aber nie welche.
Fragen oder ein Anwendungsfall, den die API noch nicht abdeckt? Schreib uns an hello@cocobook.app.