Erreurs et pagination

Ce guide décrit comment l'API de Rently communique les erreurs (structure JSON et codes), ce que signifient les codes de statut HTTP les plus courants, et comment parcourir les réponses paginées avec les paramètres offset et limit.

Tous les exemples supposent que vous avez déjà obtenu un token Bearer. Consultez le guide d'authentification pour le détail du flux. Le header d'autorisation est envoyé dans chaque appel :

Authorization: Bearer {token}

Format des erreurs

Lorsqu'une requête ne peut pas aboutir à cause d'une erreur métier ou de validation, l'API répond avec un corps JSON ayant la structure suivante :

Champ	Type	Description
ErrorMessage	string (nullable)	Message lisible décrivant l'erreur.
ErrorCode	integer	Code numérique identifiant le type d'erreur (voir le tableau des codes).
Id	string (nullable)	Identifiant de corrélation pour retracer l'erreur auprès du support.

remarque

ErrorCode est toujours sérialisé comme un nombre entier, et non comme du texte. Par exemple, 1 correspond à CustomerNotFound.

Exemple de réponse d'erreur

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

astuce

Conservez la valeur d'Id dans vos logs. C'est l'identifiant de corrélation qui permet au support de Rently de localiser la trace exacte de la requête qui a échoué.

Codes d'erreur (ErrorCode)

Le champ ErrorCode provient d'une énumération à valeurs numériques. Le tableau suivant répertorie tous les codes d'erreur que l'API peut renvoyer :

Code	Name	Description
0	NoError	Aucune erreur ne s'est produite.
1	CustomerNotFound	Le client demandé est introuvable dans le système.
2	CarNotFound	Le véhicule demandé est introuvable dans le système.
3	CarNotAvailable	Le véhicule demandé n'est pas disponible pour les dates spécifiées.
4	PriceMismatch	Le prix calculé ne correspond pas au prix attendu.
5	CustomerDataNotValid	Les données client fournies ne sont pas valides.
6	LanguageNotSupported	La langue demandée n'est pas prise en charge par le système.
7	InsuficientPermissions	L'utilisateur ne dispose pas des autorisations suffisantes pour effectuer l'opération.
8	BookingNotFoundForCustomer	Aucune réservation n'a été trouvée pour le client spécifié.
9	BookingStatusNotAllowCancel	Le statut actuel de la réservation ne permet pas l'annulation.
10	CreditCardNotAvailable	La carte de crédit n'est pas disponible.
11	GatewayNotSupported	La passerelle de paiement demandée n'est pas prise en charge.
12	InfractionNotFound	L'infraction demandée est introuvable.
13	InvlaidDates	Les dates fournies sont invalides.
14	UnquotedReserve	La réservation n'a pas été cotée.
15	MaxDayForQuotedReserve	Le nombre maximal de jours pour une réservation cotée a été dépassé.
21	TariffNotFound	Le tarif demandé est introuvable.
22	BookingNotFound	La réservation demandée est introuvable.
23	ReturnPlaceNotFound	Le lieu de retour spécifié est introuvable.
24	PromotionNotFound	La promotion demandée est introuvable.
25	DeliveryPlaceNotFound	Le lieu de livraison spécifié est introuvable.
26	BookingStatusNotAllowUpdate	Le statut actuel de la réservation ne permet pas les mises à jour.
27	IlimitedKmNotEnabled	L'option kilométrage illimité n'est pas activée.
28	LimitedKmNotEnabled	L'option kilométrage limité n'est pas activée.
29	MinimunDaysOfBookingNotReached	Le nombre minimal de jours pour la réservation n'a pas été atteint.
30	MaxDaysOfBookingReached	Le nombre maximal de jours pour la réservation a été dépassé.
31	AdditionalNotFound	L'article additionnel demandé est introuvable.
32	AdditionalMaxQuantityExceeded	La quantité maximale pour l'article additionnel a été dépassée.
33	DateFromForBookingNotEnabled	La date de début de la réservation n'est pas activée.
34	DriverAgeNotAllowed	L'âge du conducteur n'est pas dans la plage autorisée.
35	BookingVersionError	Il existe un décalage de version avec la réservation.
36	BookingAlreadyDelivered	La réservation a déjà été livrée.
37	BookingAlreadyReturned	La réservation a déjà été retournée.
38	BookingNeedsToCompleteDeposit	La réservation nécessite un dépôt pour être finalisée.
39	InvalidCarKilometers	La valeur du kilométrage du véhicule est invalide.
40	BookingStatusNotAllowDelivery	Le statut actuel de la réservation ne permet pas la livraison.
41	DriverLicenseInvalid	Le permis de conduire est invalide.
42	BookingStatusNotAllowReturn	Le statut actuel de la réservation ne permet pas le retour.
43	NotificationRelatedEntityNotFound	L'entité liée à la notification est introuvable.
44	NotificationReceiverAddressInvalid	L'adresse du destinataire de la notification est invalide.
45	MailNotificationDisabled	Les notifications par e-mail sont désactivées.
46	ReturnPlaceNotAllowedForDeliveryPlace	Le lieu de retour n'est pas autorisé pour le lieu de livraison spécifié.
47	BookingOutOfOfficeHoursNotAllowed	Les réservations en dehors des heures d'ouverture ne sont pas autorisées.
48	NotificationNotFound	La notification demandée est introuvable.
49	BlockedCustomerToBook	Le client est bloqué et ne peut pas effectuer de réservations.
50	MustHaveAtLeastOneInsurance	La configuration du système exige la sélection d'au moins une assurance lors de la création ou de la modification d'une réservation.
51	InvalidCommercialAgreement	L'accord commercial est invalide.
60	AppProtocolNotFound	Le protocole d'application est introuvable.
61	ServiceTypeInvalid	Le type de service est invalide.
62	ServiceStatusInvalid	Le statut du service est invalide.
63	ServiceDatesInvalids	Les dates du service sont invalides.
64	ServiceProviderNotFound	Le prestataire de service est introuvable.
65	ServiceCanNotCreate	Le service ne peut pas être créé.
66	ServiceCanNotEdit	Le service ne peut pas être modifié.
67	ServiceNotFound	Le service demandé est introuvable.
68	CarLocationInvalidDriver	L'emplacement du véhicule a un conducteur invalide.
69	ReturnPlaceIsCurrentPlaceError	Le lieu de retour est identique au lieu actuel.
70	CarIsNotFree	Le véhicule n'est pas disponible pour l'opération demandée.
71	CarTransferError	Une erreur s'est produite lors du transfert du véhicule.
72	InvalidCarGasoline	Le niveau de carburant du véhicule est invalide.
73	CannotDeliverBookingWithBalance	Impossible de livrer une réservation présentant un solde impayé.
74	PlaceDoesNotAcceptCustomAddresses	Le lieu n'accepte pas les adresses personnalisées.
75	PlaceCantOperatesLikePickUp	Le lieu ne peut pas servir de point de prise en charge.
76	PlaceCantOperatesLikeDropOff	Le lieu ne peut pas servir de point de restitution.
77	CannotPayQuote	Impossible de payer le devis.
80	FeatureNotEnabled	La fonctionnalité demandée n'est pas activée.
98	ModelNotValid	Le modèle n'est pas valide.
99	Unknown	Une erreur inconnue s'est produite.
100	MissingCurrencyCode	Le code de devise est manquant.
101	TotalGreaterThanZero	Le montant total doit être supérieur à zéro.
102	InfractionAlreadyExists	L'acte d'infraction ou la contravention existe déjà dans le système.
103	InvalidIncidentType	Le type d'incident est invalide
104	InvalidIncidentDate	La date de l'incident est invalide
105	SettingNotFound	Un paramètre requis est introuvable
106	BookingBrandNotFound	Booking Brand introuvable
107	BookingCannotBeUncancelled	—
108	RateAlreadyExists	Un débit avec le code donné existe déjà et aucune mise à jour n’a été demandée.
499	Timeout	—
1100	MappingAlreadyExists	—
1101	ModelNotExists	—
1102	CompanyCodeNotFound	—
1103	CommercialAgreementNotSupported	L'accord commercial n'est pas pris en charge.
1104	CommercialAgreementRequired	—
1105	InfractionNoticeNotFound	L’avis d’infraction mentionné n’a pas été trouvé pour le locataire.
1106	InfractionNoticeDismissed	L’InfractionNotice mentionné est rejeté et ne peut être lié.
1107	InfractionNoticeContextMismatch	Le contexte de l’infraction (voiture, date, réservation ou conducteur) ne correspond pas à l’InfractionNotice.
1108	InfractionNoticeMainAlreadyLinked	L’InfractionNotice contient déjà une infraction principale associée.
1109	InfractionNoticeNicAlreadyLinked	L’InfractionNotice inclut déjà une infraction NIC (pénalité de non-identification du conducteur).
1110	InfractionNoticeInfractionAlreadyLinked	L’infraction est déjà liée à un autre InfractionNotice.

attention

Les valeurs numériques ne sont pas contiguës : l'énumération saute des positions (par exemple, de 15 à 21). Mappez vos relances et vos messages à partir de la valeur exacte et ne supposez pas de plages consécutives.

Codes de statut HTTP

L'API utilise un ensemble restreint de codes de statut. Notez que les échecs d'authentification sont signalés par un 403 (l'API ne renvoie pas 401).

Statut	Signification	Corps
200 OK	La requête a été traitée correctement.	Payload de la ressource ou résultat paginé.
400 Bad Request	Erreur métier ou de validation (Api Error).	JSON avec ErrorMessage, ErrorCode et Id.
403 Forbidden	Utilisateur non authentifié ou sans permissions pour l'endpoint.	Sans corps.
404 Not Found	La ressource demandée n'existe pas.	Sans corps.

remarque

Un 403 peut signifier aussi bien que le token est invalide ou absent que l'utilisateur authentifié n'a pas la permission requise pour cet endpoint. Vérifiez d'abord le header Authorization, puis les permissions de l'utilisateur.

Comment gérer les erreurs

• 200 → traitez la réponse normalement.
• 400 → lisez ErrorCode pour décider de l'action (corriger les données, recalculer le devis, etc.) et affichez ErrorMessage à l'opérateur.
• 403 → vérifiez que le token est valide, en cours de validité et qu'il correspond au même tenant ; confirmez que l'utilisateur a les permissions.
• 404 → l'identifiant utilisé ne correspond à aucune ressource ; validez les IDs avant de réessayer.

Pagination

Les endpoints qui renvoient des listes (par exemple GET /api/bookings/list, GET /api/customers ou GET /api/cars) utilisent la pagination par offset et limit.

Paramètres de requête

Paramètre	Type	Default	Description
offset	integer	0	Point de départ de la page. Doit être >= 0.
limit	integer	30	Nombre maximum d'éléments par page. Limité à un maximum de 100.

remarque

Si vous envoyez un limit supérieur à 100, l'API le limite automatiquement à 100. Un offset négatif est normalisé à 0.

Forme du résultat

Les réponses paginées partagent la même structure PagedResult :

Champ	Type	Description
Offset	integer	Offset appliqué à cette page.
Limit	integer	Limite appliquée à cette page.
Total	integer	Total d'éléments disponibles sur toutes les pages.
Results	array (nullable)	Éléments de la page actuelle.
NextOffset	integer	Offset à utiliser pour demander la page suivante.

Exemple de réponse paginée

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

Exemple de requête

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

Comment parcourir toutes les pages

Pour itérer sur la totalité d'une liste, utilisez le NextOffset de chaque réponse comme offset de la requête suivante. L'itération se termine lorsque Results renvoie moins d'éléments que Limit.

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

# Page 2 : utiliser le NextOffset renvoyé par la page précédente
curl "https://{tenant}.rently.com.ar/api/bookings/list?offset={NextOffset}&limit=30&language=es-AR" \
  -H "Authorization: Bearer {token}"

astuce

Pour l'itération, basez-vous sur Results.Count < Limit comme condition de fin plutôt que de comparer à Total. Cela fonctionne de manière cohérente avec les deux styles de pagination de l'API.

attention

Dans GET /api/bookings/list, le paramètre offset fonctionne comme un curseur par Id, et non comme un nombre d'enregistrements à sauter. Passez toujours 0 au premier appel (quel que soit le sens du tri) et, dans les suivants, la valeur de NextOffset renvoyée par la réponse précédente. Ne construisez pas l'offset manuellement en additionnant des tailles de page.