Zum Inhalt springen

Einstieg

Fehler

Jeder Fehler hat dieselbe Form. Es gibt keine Sackgassen: hint nennt immer einen nächsten Schritt.

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).

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.

Die Meldung beginnt mit dem Pfad des ersten Feldes, das nicht passt.

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

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:

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

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

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

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/"
}
}
Terminal-Fenster
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."
}'

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

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/"
}
}
  • Auf code verzweigen, nicht auf den Text von message. Der Text wird übersetzt und kann sich ändern.
  • hint mitschreiben. 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.