Einstieg
Fehler
Jeder Fehler hat dieselbe Form. Es gibt keine Sackgassen: hint nennt immer einen nächsten Schritt.
Fehlerformat
Abschnitt betitelt „Fehlerformat“Antwort404Not Found
- Content-Type
- application/json; charset=utf-8
- Content-Language
- de
- Cache-Control
- no-store
{ "error": { "code": "not_found", "message": "Diese Buchung gibt es nicht.", "status": 404, "hint": "Die Referenz prüfen.", "documentation_url": "https://skirent.sumware.at/api/" }}| Feld | Für wen | |
|---|---|---|
code |
Maschinen | Ändert sich nie. Darauf verzweigt Ihr Programm. |
message |
Menschen | In der Sprache der Anfrage. |
status |
Maschinen | Der HTTP-Status noch einmal im Rumpf, weil Zwischenschichten ihn gelegentlich verschlucken. |
hint |
Menschen | Der nächste Schritt. |
documentation_url |
beide | Verweis auf die Liste der Endpunkte unter der gerufenen Adresse. |
Fehler werden nie zwischengespeichert (Cache-Control: no-store).
Fehlercodes
Abschnitt betitelt „Fehlercodes“| Status | code |
Wann |
|---|---|---|
| 400 | invalid_request |
Die Anfrage ist nicht gültig. Die Meldung nennt das erste Feld. |
| 401 | unauthorized |
Der Schlüssel fehlt, ist falsch, abgelaufen oder widerrufen. |
| 403 | forbidden |
Dem Schlüssel fehlt ein Recht. Die Meldung nennt es beim Namen. |
| 404 | not_found |
Diesen Eintrag gibt es nicht. |
| 405 | method_not_allowed |
Der Pfad ist bekannt, die Methode nicht. Allow nennt die erlaubten. |
| 409 | conflict |
Die Anfrage widerspricht dem Stand, etwa ein zweites Storno. |
| 429 | rate_limited |
Zu viele Anfragen. Retry-After nennt die Wartezeit in Sekunden. |
| 500 | internal_error |
Ein Fehler im Server. Die Antwort nennt keine Einzelheiten. |
| 503 | service_unavailable |
Vorübergehend nicht erreichbar, etwa während einer Wartung des Betriebs. |
Dazu gibt es payment_unavailable im Bezahlweg der Website. Über die offene Schnittstelle wird nicht bezahlt, dort kommt er nicht vor.
Beispiele
Abschnitt betitelt „Beispiele“Ungültige Anfrage
Abschnitt betitelt „Ungültige Anfrage“Die Meldung beginnt mit dem Pfad des ersten Feldes, das nicht passt.
curl -X POST "https://skirent.sumware.at/api/ext/v1/bookings" \ -H "Authorization: Bearer $SKI4ME_KEY" \ -H "Content-Type: application/json" \ -d '{ "items": [], "customer": { "firstName": "Ohne" }, "stay": { "arrivalOn": "2026-12-27" } }'const res = await fetch("https://skirent.sumware.at/api/ext/v1/bookings", { method: "POST", headers: { Authorization: `Bearer ${process.env.SKI4ME_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ items: [], customer: { firstName: "Ohne" }, stay: { arrivalOn: "2026-12-27" }, }),});
const data = await res.json();if (!res.ok) throw new Error(`${data.error.code}: ${data.error.hint}`);console.log(data);import osimport requests
res = requests.post( "https://skirent.sumware.at/api/ext/v1/bookings", headers={"Authorization": f"Bearer {os.environ['SKI4ME_KEY']}"}, json={ "items": [], "customer": {"firstName": "Ohne"}, "stay": {"arrivalOn": "2026-12-27"}, }, timeout=10,)data = res.json()if not res.ok: raise RuntimeError(f"{data['error']['code']}: {data['error']['hint']}")print(data)<?php
$ch = curl_init('https://skirent.sumware.at/api/ext/v1/bookings');curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 10, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('SKI4ME_KEY'), 'Content-Type: application/json', ], CURLOPT_POSTFIELDS => json_encode([ 'items' => [], 'customer' => ['firstName' => 'Ohne'], 'stay' => ['arrivalOn' => '2026-12-27'], ]),]);$body = curl_exec($ch);$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
$data = json_decode($body, true);if ($status >= 400) { throw new RuntimeException($data['error']['code'] . ': ' . $data['error']['hint']);}print_r($data);Antwort400Bad Request
{ "error": { "code": "invalid_request", "message": "Feld items: Too small: expected array to have >=1 items", "status": 400, "hint": "Die erwarteten Parameter stehen unter https://skirent.sumware.at/api/.", "documentation_url": "https://skirent.sumware.at/api/" }}Manche Regeln stehen nicht im Schema, sondern im Ablauf. Dann sagt der Hinweis, was zu senden ist:
curl -X PATCH "https://skirent.sumware.at/api/ext/v1/jobs/5" \ -H "Authorization: Bearer $SKI4ME_KEY" \ -H "Content-Type: application/json" \ -d '{ "status": "skipped" }'const res = await fetch("https://skirent.sumware.at/api/ext/v1/jobs/5", { method: "PATCH", headers: { Authorization: `Bearer ${process.env.SKI4ME_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ status: "skipped" }),});
const data = await res.json();if (!res.ok) throw new Error(`${data.error.code}: ${data.error.hint}`);console.log(data);import osimport requests
res = requests.patch( "https://skirent.sumware.at/api/ext/v1/jobs/5", headers={"Authorization": f"Bearer {os.environ['SKI4ME_KEY']}"}, json={"status": "skipped"}, timeout=10,)data = res.json()if not res.ok: raise RuntimeError(f"{data['error']['code']}: {data['error']['hint']}")print(data)<?php
$ch = curl_init('https://skirent.sumware.at/api/ext/v1/jobs/5');curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 10, CURLOPT_CUSTOMREQUEST => 'PATCH', CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('SKI4ME_KEY'), 'Content-Type: application/json', ], CURLOPT_POSTFIELDS => json_encode(['status' => 'skipped']),]);$body = curl_exec($ch);$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
$data = json_decode($body, true);if ($status >= 400) { throw new RuntimeException($data['error']['code'] . ': ' . $data['error']['hint']);}print_r($data);Antwort400Bad Request
{ "error": { "code": "invalid_request", "message": "Ein übersprungener Auftrag braucht einen Grund.", "status": 400, "hint": "Feld skipReason mitsenden, etwa \"niemand angetroffen\".", "documentation_url": "https://skirent.sumware.at/api/" }}Bei einem Wert aus einer festen Auswahl nennt der Hinweis die Auswahl:
Antwort400Bad Request
{ "error": { "code": "invalid_request", "message": "Diesen Status gibt es nicht.", "status": 400, "hint": "Erlaubt: pending_payment, paid, confirmed, delivered, collected, closed, cancelled, payment_failed, needs_review, expired.", "documentation_url": "https://skirent.sumware.at/api/" }}Fehlendes Recht
Abschnitt betitelt „Fehlendes Recht“Antwort403Forbidden
{ "error": { "code": "forbidden", "message": "Diesem Schlüssel fehlt: booking.view.", "status": 403, "hint": "Im Portal unter Einstellungen, Schnittstelle, einen Schlüssel mit diesem Recht anlegen.", "documentation_url": "https://skirent.sumware.at/api/" }}Falsche Methode
Abschnitt betitelt „Falsche Methode“Ein bekannter Pfad mit falscher Methode ist 405 und nie 404. Ein Programm, das auf „nicht gefunden“ läuft, sucht sonst weiter nach etwas, das es längst gefunden hat.
Antwort405Method Not Allowed
- Allow
- GET, HEAD, OPTIONS, PATCH
{ "error": { "code": "method_not_allowed", "message": "DELETE wird hier nicht angenommen.", "status": 405, "hint": "Diesen Pfad mit GET oder HEAD oder OPTIONS oder PATCH aufrufen.", "documentation_url": "https://skirent.sumware.at/api/" }}Widerspruch zum Stand
Abschnitt betitelt „Widerspruch zum Stand“curl -X POST "https://skirent.sumware.at/api/ext/v1/bookings/SB-261112-WDZH/cancel" \ -H "Authorization: Bearer $SKI4ME_KEY" \ -H "Content-Type: application/json" \ -d '{ "rentalRefundCents": 0, "reason": "Noch einmal." }'const res = await fetch("https://skirent.sumware.at/api/ext/v1/bookings/SB-261112-WDZH/cancel", { method: "POST", headers: { Authorization: `Bearer ${process.env.SKI4ME_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ rentalRefundCents: 0, reason: "Noch einmal." }),});
const data = await res.json();if (!res.ok) throw new Error(`${data.error.code}: ${data.error.hint}`);console.log(data);import osimport requests
res = requests.post( "https://skirent.sumware.at/api/ext/v1/bookings/SB-261112-WDZH/cancel", headers={"Authorization": f"Bearer {os.environ['SKI4ME_KEY']}"}, json={"rentalRefundCents": 0, "reason": "Noch einmal."}, timeout=10,)data = res.json()if not res.ok: raise RuntimeError(f"{data['error']['code']}: {data['error']['hint']}")print(data)<?php
$ch = curl_init('https://skirent.sumware.at/api/ext/v1/bookings/SB-261112-WDZH/cancel');curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 10, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('SKI4ME_KEY'), 'Content-Type: application/json', ], CURLOPT_POSTFIELDS => json_encode(['rentalRefundCents' => 0, 'reason' => 'Noch einmal.']),]);$body = curl_exec($ch);$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
$data = json_decode($body, true);if ($status >= 400) { throw new RuntimeException($data['error']['code'] . ': ' . $data['error']['hint']);}print_r($data);Antwort409Conflict
{ "error": { "code": "conflict", "message": "Diese Buchung ist schon storniert.", "status": 409, "hint": "Im Verlauf steht, wann und von wem.", "documentation_url": "https://skirent.sumware.at/api/" }}Bei Unterkünften nennt der Hinweis den Eintrag, mit dem die Anfrage zusammenstößt:
Antwort409Conflict
{ "error": { "code": "conflict", "message": "\"Hotel Alpenhof\" steht schon in der Liste.", "status": 409, "hint": "Den vorhandenen Eintrag bearbeiten statt einen zweiten anzulegen.", "documentation_url": "https://skirent.sumware.at/api/" }}Zu viele Anfragen
Abschnitt betitelt „Zu viele Anfragen“Antwort429Too Many Requests
- Retry-After
- 46
- X-RateLimit-Limit
- 600
- X-RateLimit-Remaining
- 0
- X-RateLimit-Reset
- 1798391160
{ "error": { "code": "rate_limited", "message": "Zu viele Anfragen in kurzer Zeit.", "status": 429, "hint": "In 46 Sekunden erneut versuchen.", "documentation_url": "https://skirent.sumware.at/api/" }}Empfehlungen
Abschnitt betitelt „Empfehlungen“- Auf
codeverzweigen, nicht auf den Text vonmessage. Der Text wird übersetzt und kann sich ändern. hintmitschreiben. Er spart die Rückfrage beim Betrieb.- 401 nicht wiederholen. Ein Schlüssel, der nicht gilt, gilt auch beim zweiten Versuch nicht.
- 429 und 503 mit Abstand wiederholen, bei 429 frühestens nach
Retry-After. - 404 bei einer Buchung ernst nehmen. Eine Buchungsnummer eines anderen Betriebs ist für Ihren Schlüssel nicht vorhanden.