Fehler und Paginierung

Dieser Leitfaden beschreibt, wie die Rently API Fehler kommuniziert (JSON-Struktur und Codes), was die häufigsten HTTP-Statuscodes bedeuten und wie Sie paginierte Antworten mit den Parametern offset und limit durchlaufen.

Alle Beispiele setzen voraus, dass Sie bereits ein Bearer-Token erlangt haben. Den genauen Ablauf finden Sie im Authentifizierungsleitfaden. Der Autorisierungsheader wird bei jedem Aufruf gesendet:

Authorization: Bearer {token}

Fehlerformat

Wenn eine Anfrage aufgrund eines Geschäfts- oder Validierungsfehlers nicht abgeschlossen werden kann, antwortet die API mit einem JSON-Body folgender Struktur:

Feld	Typ	Beschreibung
ErrorMessage	string (nullable)	Lesbare Meldung, die den Fehler beschreibt.
ErrorCode	integer	Numerischer Code, der den Fehlertyp identifiziert (siehe Code-Tabelle).
Id	string (nullable)	Korrelations-ID, um den Fehler beim Support nachzuverfolgen.

Hinweis

ErrorCode wird stets als Ganzzahl serialisiert, nicht als Text. Zum Beispiel entspricht 1 dem Wert CustomerNotFound.

Beispiel einer Fehlerantwort

{
  "ErrorMessage": "The requested resource was not found",
  "ErrorCode": 1,
  "Id": "0HMVB9A2K3C4D-00000001"
}

Tipp

Speichern Sie den Wert von Id in Ihren Logs. Es ist die Korrelations-ID, mit der der Rently-Support die genaue Trace der fehlgeschlagenen Anfrage finden kann.

Fehlercodes (ErrorCode)

Die folgende Tabelle listet alle Fehlercodes auf, die die API zurückgeben kann:

Code	Name	Description
0	NoError	Es ist kein Fehler aufgetreten.
1	CustomerNotFound	Der angeforderte Kunde wurde im System nicht gefunden.
2	CarNotFound	Das angeforderte Fahrzeug wurde im System nicht gefunden.
3	CarNotAvailable	Das angeforderte Fahrzeug ist für die angegebenen Daten nicht verfügbar.
4	PriceMismatch	Der berechnete Preis stimmt nicht mit dem erwarteten Preis überein.
5	CustomerDataNotValid	Die bereitgestellten Kundendaten sind ungültig.
6	LanguageNotSupported	Die angeforderte Sprache wird vom System nicht unterstützt.
7	InsuficientPermissions	Der Benutzer verfügt nicht über ausreichende Berechtigungen, um den Vorgang auszuführen.
8	BookingNotFoundForCustomer	Für den angegebenen Kunden wurde keine Buchung gefunden.
9	BookingStatusNotAllowCancel	Der aktuelle Buchungsstatus lässt keine Stornierung zu.
10	CreditCardNotAvailable	Die Kreditkarte steht nicht zur Verfügung.
11	GatewayNotSupported	Das angeforderte Zahlungs-Gateway wird nicht unterstützt.
12	InfractionNotFound	Der angeforderte Verstoß wurde nicht gefunden.
13	InvlaidDates	Die angegebenen Daten sind ungültig.
14	UnquotedReserve	Für die Reservierung wurde noch kein Angebot erstellt.
15	MaxDayForQuotedReserve	Die maximale Anzahl an Tagen für eine angebotene Reservierung wurde überschritten.
21	TariffNotFound	Der angeforderte Tarif wurde nicht gefunden.
22	BookingNotFound	Die angeforderte Buchung wurde nicht gefunden.
23	ReturnPlaceNotFound	Der angegebene Rückgabeort wurde nicht gefunden.
24	PromotionNotFound	Die angeforderte Aktion wurde nicht gefunden.
25	DeliveryPlaceNotFound	Der angegebene Übergabeort wurde nicht gefunden.
26	BookingStatusNotAllowUpdate	Der aktuelle Buchungsstatus lässt keine Aktualisierungen zu.
27	IlimitedKmNotEnabled	Die Option für unbegrenzte Kilometer ist nicht aktiviert.
28	LimitedKmNotEnabled	Die Option für begrenzte Kilometer ist nicht aktiviert.
29	MinimunDaysOfBookingNotReached	Die Mindestanzahl an Tagen für eine Buchung wurde nicht erreicht.
30	MaxDaysOfBookingReached	Die maximale Anzahl an Tagen für eine Buchung wurde überschritten.
31	AdditionalNotFound	Das angeforderte Zusatzangebot wurde nicht gefunden.
32	AdditionalMaxQuantityExceeded	Die maximale Menge für das Zusatzangebot wurde überschritten.
33	DateFromForBookingNotEnabled	Das Startdatum für die Buchung ist nicht zulässig.
34	DriverAgeNotAllowed	Das Alter des Fahrers liegt nicht innerhalb des zulässigen Bereichs.
35	BookingVersionError	Es liegt eine Versionskonflikt mit der Buchung vor.
36	BookingAlreadyDelivered	Die Buchung wurde bereits übergeben.
37	BookingAlreadyReturned	Die Buchung wurde bereits zurückgegeben.
38	BookingNeedsToCompleteDeposit	Für die Buchung ist eine Kaution erforderlich, um sie abzuschließen.
39	InvalidCarKilometers	Der Kilometerstand des Fahrzeugs ist ungültig.
40	BookingStatusNotAllowDelivery	Der aktuelle Buchungsstatus lässt keine Übergabe zu.
41	DriverLicenseInvalid	Der Führerschein des Fahrers ist ungültig.
42	BookingStatusNotAllowReturn	Der aktuelle Buchungsstatus lässt keine Rückgabe zu.
43	NotificationRelatedEntityNotFound	Die zugehörige Entität der Benachrichtigung wurde nicht gefunden.
44	NotificationReceiverAddressInvalid	Die Adresse des Benachrichtigungsempfängers ist ungültig.
45	MailNotificationDisabled	E-Mail-Benachrichtigungen sind deaktiviert.
46	ReturnPlaceNotAllowedForDeliveryPlace	Der Rückgabeort ist für den angegebenen Übergabeort nicht zulässig.
47	BookingOutOfOfficeHoursNotAllowed	Buchungen außerhalb der Öffnungszeiten sind nicht zulässig.
48	NotificationNotFound	Die angeforderte Benachrichtigung wurde nicht gefunden.
49	BlockedCustomerToBook	Der Kunde ist für Buchungen gesperrt.
50	MustHaveAtLeastOneInsurance	Die Systemkonfiguration erfordert, dass beim Erstellen oder Bearbeiten einer Buchung mindestens eine Versicherung ausgewählt wird.
51	InvalidCommercialAgreement	Die Geschäftsvereinbarung ist ungültig.
60	AppProtocolNotFound	Das Anwendungsprotokoll wurde nicht gefunden.
61	ServiceTypeInvalid	Der Diensttyp ist ungültig.
62	ServiceStatusInvalid	Der Dienststatus ist ungültig.
63	ServiceDatesInvalids	Die Dienstdaten sind ungültig.
64	ServiceProviderNotFound	Der Dienstanbieter wurde nicht gefunden.
65	ServiceCanNotCreate	Der Dienst kann nicht erstellt werden.
66	ServiceCanNotEdit	Der Dienst kann nicht bearbeitet werden.
67	ServiceNotFound	Der angeforderte Dienst wurde nicht gefunden.
68	CarLocationInvalidDriver	Der Fahrzeugstandort hat einen ungültigen Fahrer.
69	ReturnPlaceIsCurrentPlaceError	Der Rückgabeort ist mit dem aktuellen Ort identisch.
70	CarIsNotFree	Das Fahrzeug ist für den angeforderten Vorgang nicht verfügbar.
71	CarTransferError	Beim Fahrzeugtransfer ist ein Fehler aufgetreten.
72	InvalidCarGasoline	Der Kraftstoffstand des Fahrzeugs ist ungültig.
73	CannotDeliverBookingWithBalance	Eine Buchung mit offenem Saldo kann nicht übergeben werden.
74	PlaceDoesNotAcceptCustomAddresses	Der Ort akzeptiert keine benutzerdefinierten Adressen.
75	PlaceCantOperatesLikePickUp	Der Ort kann nicht als Übergabeort fungieren.
76	PlaceCantOperatesLikeDropOff	Der Ort kann nicht als Rückgabeort fungieren.
77	CannotPayQuote	Das Angebot kann nicht bezahlt werden.
80	FeatureNotEnabled	Die angeforderte Funktion ist nicht aktiviert.
98	ModelNotValid	Das Modell ist ungültig.
99	Unknown	Es ist ein unbekannter Fehler aufgetreten.
100	MissingCurrencyCode	Der Währungscode fehlt.
101	TotalGreaterThanZero	Der Gesamtbetrag muss größer als null sein.
102	InfractionAlreadyExists	Der Verstoßbescheid oder die Ordnungswidrigkeit existiert bereits im System.
103	InvalidIncidentType	Der Vorfalltyp ist ungültig
104	InvalidIncidentDate	Das Vorfalldatum ist ungültig
105	SettingNotFound	Eine erforderliche Einstellung wurde nicht gefunden
106	BookingBrandNotFound	Booking Brand nicht gefunden
107	BookingCannotBeUncancelled	—
108	RateAlreadyExists	Eine Rate mit dem angegebenen Code existiert bereits und Updates wurden nicht angefordert.
499	Timeout	—
1100	MappingAlreadyExists	—
1101	ModelNotExists	—
1102	CompanyCodeNotFound	—
1103	CommercialAgreementNotSupported	Die Geschäftsvereinbarung wird nicht unterstützt.
1104	CommercialAgreementRequired	—
1105	InfractionNoticeNotFound	Die referenzierte InfractionNotice wurde für den Mieter nicht gefunden.
1106	InfractionNoticeDismissed	Die referenzierte InfractionNotice wird abgelehnt und kann nicht verknüpft werden.
1107	InfractionNoticeContextMismatch	Der Kontext der Verstöße (Auto, Datum, Buchung oder Fahrer) stimmt nicht mit der InfractionNotice überein.
1108	InfractionNoticeMainAlreadyLinked	Der InfractionNotice hat bereits einen Hauptverstoß verknüpft.
1109	InfractionNoticeNicAlreadyLinked	Die InjurisdictionNotice hat bereits eine NIC (Fahrer-Nicht-Identifikationsstrafe) verknüpft.
1110	InfractionNoticeInfractionAlreadyLinked	Der Verstoß ist bereits mit einem anderen InfractionNotice verknüpft.

Warnung

Die numerischen Werte sind nicht zusammenhängend: Die Enumeration überspringt Positionen (zum Beispiel von 15 zu 21). Ordnen Sie Ihre Wiederholungen und Meldungen anhand des genauen Werts zu und gehen Sie nicht von fortlaufenden Bereichen aus.

HTTP-Statuscodes

Die API verwendet einen begrenzten Satz von Statuscodes. Beachten Sie, dass Authentifizierungsfehler als 403 gemeldet werden (die API gibt kein 401 zurück).

Status	Bedeutung	Body
200 OK	Die Anfrage wurde erfolgreich verarbeitet.	Payload der Ressource oder paginiertes Ergebnis.
400 Bad Request	Geschäfts- oder Validierungsfehler (Api Error).	JSON mit ErrorMessage, ErrorCode und Id.
403 Forbidden	Benutzer nicht authentifiziert oder keine Berechtigung für den Endpunkt.	Ohne Body.
404 Not Found	Die angefragte Ressource existiert nicht.	Ohne Body.

Hinweis

Ein 403 kann sowohl bedeuten, dass das Token ungültig oder nicht vorhanden ist, als auch, dass der authentifizierte Benutzer nicht die für diesen Endpunkt erforderliche Berechtigung hat. Prüfen Sie zuerst den Header Authorization und danach die Berechtigungen des Benutzers.

So behandeln Sie Fehler

• 200 → verarbeiten Sie die Antwort normal.
• 400 → lesen Sie ErrorCode, um die Aktion zu bestimmen (Daten korrigieren, neu kalkulieren usw.), und zeigen Sie ErrorMessage dem Bediener an.
• 403 → prüfen Sie, ob das Token gültig, aktuell und zum selben Mandanten gehörig ist; stellen Sie sicher, dass der Benutzer die Berechtigung hat.
• 404 → die verwendete Kennung entspricht keiner Ressource; validieren Sie die IDs, bevor Sie es erneut versuchen.

Paginierung

Endpunkte, die Listen zurückgeben (zum Beispiel GET /api/bookings/list, GET /api/customers oder GET /api/cars), verwenden Paginierung über offset und limit.

Query-Parameter

Parameter	Typ	Default	Beschreibung
offset	integer	0	Startpunkt der Seite. Muss >= 0 sein.
limit	integer	30	Maximale Anzahl der Elemente pro Seite. Wird auf maximal 100 beschnitten.

Hinweis

Senden Sie ein limit größer als 100, beschneidet die API es automatisch auf 100. Ein negatives offset wird auf 0 normalisiert.

Form des Ergebnisses

Paginierte Antworten teilen dieselbe Struktur PagedResult:

Feld	Typ	Beschreibung
Offset	integer	Auf diese Seite angewendetes Offset.
Limit	integer	Auf diese Seite angewendetes Limit.
Total	integer	Gesamtzahl der über alle Seiten verfügbaren Elemente.
Results	array (nullable)	Elemente der aktuellen Seite.
NextOffset	integer	Offset, das zum Anfordern der nächsten Seite zu verwenden ist.

Beispiel einer paginierten Antwort

{
  "Offset": 0,
  "Limit": 30,
  "Total": 2,
  "Results": [
    { "Id": 1 },
    { "Id": 2 }
  ],
  "NextOffset": 0
}

Beispiel einer Anfrage

curl "https://{tenant}.rently.com.ar/api/customers?offset=0&limit=30&language=es-AR" \
  -H "Authorization: Bearer {token}"

So durchlaufen Sie alle Seiten

Um eine vollständige Liste zu durchlaufen, verwenden Sie das NextOffset jeder Antwort als offset der folgenden Anfrage. Die Iteration endet, wenn Results weniger Elemente als Limit liefert.

# Seite 1
curl "https://{tenant}.rently.com.ar/api/bookings/list?offset=0&limit=30&language=es-AR" \
  -H "Authorization: Bearer {token}"

# Seite 2: das von der vorherigen Seite zurückgegebene NextOffset verwenden
curl "https://{tenant}.rently.com.ar/api/bookings/list?offset={NextOffset}&limit=30&language=es-AR" \
  -H "Authorization: Bearer {token}"

Tipp

Achten Sie für die Iteration auf Results.Count < Limit als Abbruchbedingung, statt gegen Total zu vergleichen. Das funktioniert konsistent mit beiden Paginierungsstilen der API.

Warnung

Bei GET /api/bookings/list funktioniert der Parameter offset als Cursor nach Id, nicht als Anzahl zu überspringender Datensätze. Übergeben Sie beim ersten Aufruf immer 0 (unabhängig von der Sortierrichtung) und bei den folgenden den Wert von NextOffset, den die vorherige Antwort zurückgegeben hat. Konstruieren Sie das offset nicht manuell durch Aufsummieren von Seitengrößen.