Errori e paginazione

Questa guida descrive come l'API di Rently comunica gli errori (struttura JSON e codici), cosa significano i codici di stato HTTP più comuni, e come scorrere risposte paginate con i parametri offset e limit.

Tutti gli esempi presuppongono che tu abbia già ottenuto un token Bearer. Consulta la guida di autenticazione per il dettaglio del flusso. L'header di autorizzazione si invia in ogni chiamata:

Authorization: Bearer {token}

Formato degli errori

Quando una richiesta non può essere completata per un errore di business o di validazione, l'API risponde con un corpo JSON con la seguente struttura:

Campo	Tipo	Descrizione
ErrorMessage	string (nullable)	Messaggio leggibile che descrive l'errore.
ErrorCode	integer	Codice numerico che identifica il tipo di errore (vedi tabella dei codici).
Id	string (nullable)	Identificatore di correlazione per tracciare l'errore nel supporto.

note

ErrorCode viene serializzato sempre come numero intero, non come testo. Per esempio, 1 corrisponde a CustomerNotFound.

Esempio di risposta di errore

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

suggerimento

Salva il valore di Id nei tuoi log. È l'identificatore di correlazione che permette al supporto di Rently di individuare la traccia esatta della richiesta fallita.

Codici di errore (ErrorCode)

La tabella seguente elenca tutti i codici di errore che l'API può restituire:

Code	Name	Description
0	NoError	Nessun errore verificatosi.
1	CustomerNotFound	Il customer richiesto non è stato trovato nel sistema.
2	CarNotFound	Il car richiesto non è stato trovato nel sistema.
3	CarNotAvailable	Il car richiesto non è disponibile per le date specificate.
4	PriceMismatch	Il prezzo calcolato non corrisponde al prezzo previsto.
5	CustomerDataNotValid	I dati del customer forniti non sono validi.
6	LanguageNotSupported	La lingua richiesta non è supportata dal sistema.
7	InsuficientPermissions	L'utente non dispone di permessi sufficienti per eseguire l'operazione.
8	BookingNotFoundForCustomer	Nessun booking è stato trovato per il customer specificato.
9	BookingStatusNotAllowCancel	Lo stato attuale del booking non consente la cancellazione.
10	CreditCardNotAvailable	La carta di credito non è disponibile per l'uso.
11	GatewayNotSupported	Il gateway di pagamento richiesto non è supportato.
12	InfractionNotFound	L'infraction richiesta non è stata trovata.
13	InvlaidDates	Le date fornite non sono valide.
14	UnquotedReserve	La prenotazione non è stata quotata.
15	MaxDayForQuotedReserve	È stato superato il numero massimo di giorni per una prenotazione quotata.
21	TariffNotFound	La tariffa richiesta non è stata trovata.
22	BookingNotFound	Il booking richiesto non è stato trovato.
23	ReturnPlaceNotFound	Il luogo di restituzione specificato non è stato trovato.
24	PromotionNotFound	La promozione richiesta non è stata trovata.
25	DeliveryPlaceNotFound	Il luogo di consegna specificato non è stato trovato.
26	BookingStatusNotAllowUpdate	Lo stato attuale del booking non consente aggiornamenti.
27	IlimitedKmNotEnabled	L'opzione chilometri illimitati non è abilitata.
28	LimitedKmNotEnabled	L'opzione chilometri limitati non è abilitata.
29	MinimunDaysOfBookingNotReached	Non è stato raggiunto il numero minimo di giorni per il booking.
30	MaxDaysOfBookingReached	È stato superato il numero massimo di giorni per il booking.
31	AdditionalNotFound	L'elemento aggiuntivo richiesto non è stato trovato.
32	AdditionalMaxQuantityExceeded	È stata superata la quantità massima per l'elemento aggiuntivo.
33	DateFromForBookingNotEnabled	La data di inizio del booking non è abilitata.
34	DriverAgeNotAllowed	L'età del conducente non rientra nell'intervallo consentito.
35	BookingVersionError	È presente una discrepanza di versione con il booking.
36	BookingAlreadyDelivered	Il booking è già stato consegnato.
37	BookingAlreadyReturned	Il booking è già stato restituito.
38	BookingNeedsToCompleteDeposit	Il booking richiede un deposito per essere completato.
39	InvalidCarKilometers	Il valore dei chilometri del car non è valido.
40	BookingStatusNotAllowDelivery	Lo stato attuale del booking non consente la consegna.
41	DriverLicenseInvalid	La patente di guida non è valida.
42	BookingStatusNotAllowReturn	Lo stato attuale del booking non consente la restituzione.
43	NotificationRelatedEntityNotFound	L'entità correlata alla notifica non è stata trovata.
44	NotificationReceiverAddressInvalid	L'indirizzo del destinatario della notifica non è valido.
45	MailNotificationDisabled	Le notifiche via mail sono disabilitate.
46	ReturnPlaceNotAllowedForDeliveryPlace	Il luogo di restituzione non è consentito per il luogo di consegna specificato.
47	BookingOutOfOfficeHoursNotAllowed	Il booking al di fuori dell'orario d'ufficio non è consentito.
48	NotificationNotFound	La notifica richiesta non è stata trovata.
49	BlockedCustomerToBook	Al customer è impedito di effettuare booking.
50	MustHaveAtLeastOneInsurance	La configurazione del sistema richiede la selezione di almeno un'assicurazione durante la creazione o la modifica di un booking.
51	InvalidCommercialAgreement	L'accordo commerciale non è valido.
60	AppProtocolNotFound	Il protocollo dell'applicazione non è stato trovato.
61	ServiceTypeInvalid	Il tipo di servizio non è valido.
62	ServiceStatusInvalid	Lo stato del servizio non è valido.
63	ServiceDatesInvalids	Le date del servizio non sono valide.
64	ServiceProviderNotFound	Il fornitore del servizio non è stato trovato.
65	ServiceCanNotCreate	Il servizio non può essere creato.
66	ServiceCanNotEdit	Il servizio non può essere modificato.
67	ServiceNotFound	Il servizio richiesto non è stato trovato.
68	CarLocationInvalidDriver	La posizione del car ha un conducente non valido.
69	ReturnPlaceIsCurrentPlaceError	Il luogo di restituzione coincide con il luogo attuale.
70	CarIsNotFree	Il car non è disponibile per l'operazione richiesta.
71	CarTransferError	Si è verificato un errore durante il trasferimento del car.
72	InvalidCarGasoline	Il livello di carburante del car non è valido.
73	CannotDeliverBookingWithBalance	Impossibile consegnare un booking con un saldo in sospeso.
74	PlaceDoesNotAcceptCustomAddresses	Il luogo non accetta indirizzi personalizzati.
75	PlaceCantOperatesLikePickUp	Il luogo non può operare come punto di ritiro.
76	PlaceCantOperatesLikeDropOff	Il luogo non può operare come punto di riconsegna.
77	CannotPayQuote	Impossibile pagare la quotazione.
80	FeatureNotEnabled	La funzionalità richiesta non è abilitata.
98	ModelNotValid	Il model non è valido.
99	Unknown	Si è verificato un errore sconosciuto.
100	MissingCurrencyCode	Il codice valuta è mancante.
101	TotalGreaterThanZero	L'importo totale deve essere maggiore di zero.
102	InfractionAlreadyExists	L'atto di infraction o la violazione esiste già nel sistema.
103	InvalidIncidentType	Il tipo di incident non è valido
104	InvalidIncidentDate	La data dell'incident non è valida
105	SettingNotFound	Un'impostazione richiesta non è stata trovata
106	BookingBrandNotFound	Booking Brand non trovato
107	BookingCannotBeUncancelled	—
108	RateAlreadyExists	Un tasso con il codice indicato esiste già e non sono stati richiesti aggiornamenti.
499	Timeout	—
1100	MappingAlreadyExists	—
1101	ModelNotExists	—
1102	CompanyCodeNotFound	—
1103	CommercialAgreementNotSupported	L'accordo commerciale non è supportato.
1104	CommercialAgreementRequired	—
1105	InfractionNoticeNotFound	L'InfractionNotice citato non è stato riconosciuto per l'inquilino.
1106	InfractionNoticeDismissed	L'InfractionNotice citato è archiviato e non può essere collegato.
1107	InfractionNoticeContextMismatch	Il contesto dell'infrazione (auto, data, prenotazione o autista) non corrisponde all'InfractionNotice.
1108	InfractionNoticeMainAlreadyLinked	L'InfractionNotice ha già collegato una violazione principale.
1109	InfractionNoticeNicAlreadyLinked	L'InfractionNotice ha già collegato un'infrazione NIC (penale per non identificazione del conducente).
1110	InfractionNoticeInfractionAlreadyLinked	L'infrazione è già collegata a un diverso InfractionNotice.

warning

I valori numerici non sono contigui: l'enumerazione salta posizioni (per esempio, da 15 a 21). Mappa i tuoi retry e messaggi a partire dal valore esatto e non assumere intervalli consecutivi.

Codici di stato HTTP

L'API utilizza un insieme limitato di codici di stato. Tieni presente che i fallimenti di autenticazione vengono riportati come 403 (l'API non restituisce 401).

Stato	Significato	Corpo
200 OK	La richiesta è stata elaborata correttamente.	Payload della risorsa o risultato paginato.
400 Bad Request	Errore di business o di validazione (Api Error).	JSON con ErrorMessage, ErrorCode e Id.
403 Forbidden	Utente non autenticato o senza permessi per l'endpoint.	Senza corpo.
404 Not Found	La risorsa richiesta non esiste.	Senza corpo.

note

Un 403 può significare sia che il token non è valido o è assente, sia che l'utente autenticato non ha il permesso richiesto per quell'endpoint. Verifica prima l'header Authorization e poi i permessi dell'utente.

Come gestire gli errori

• 200 → elabora la risposta normalmente.
• 400 → leggi ErrorCode per decidere l'azione (correggere i dati, ripreventivare, ecc.) e mostra ErrorMessage all'operatore.
• 403 → controlla che il token sia valido, in corso di validità e corrisponda allo stesso tenant; conferma che l'utente abbia i permessi.
• 404 → l'identificatore usato non corrisponde ad alcuna risorsa; valida gli ID prima di riprovare.

Paginazione

Gli endpoint che restituiscono liste (per esempio GET /api/bookings/list, GET /api/customers o GET /api/cars) usano la paginazione tramite offset e limit.

Parametri di query

Parametro	Tipo	Default	Descrizione
offset	integer	0	Punto di partenza della pagina. Deve essere >= 0.
limit	integer	30	Quantità massima di elementi per pagina. Viene troncata a un massimo di 100.

note

Se invii un limit maggiore di 100, l'API lo tronca automaticamente a 100. Un offset negativo viene normalizzato a 0.

Forma del risultato

Le risposte paginate condividono la stessa struttura PagedResult:

Campo	Tipo	Descrizione
Offset	integer	Offset applicato a questa pagina.
Limit	integer	Limite applicato a questa pagina.
Total	integer	Totale di elementi disponibili in tutte le pagine.
Results	array (nullable)	Elementi della pagina corrente.
NextOffset	integer	Offset da usare per richiedere la pagina successiva.

Esempio di risposta paginata

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

Esempio di richiesta

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

Come scorrere tutte le pagine

Per iterare sull'intero elenco, usa NextOffset di ogni risposta come offset della richiesta successiva. L'iterazione termina quando Results contiene meno elementi di Limit.

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

# Pagina 2: usare il NextOffset restituito dalla pagina precedente
curl "https://{tenant}.rently.com.ar/api/bookings/list?offset={NextOffset}&limit=30&language=es-AR" \
  -H "Authorization: Bearer {token}"

suggerimento

Per l'iterazione, usa Results.Count < Limit come condizione di fine invece di confrontare con Total. Questo funziona in modo coerente con entrambi gli stili di paginazione dell'API.

warning

In GET /api/bookings/list il parametro offset funziona come cursore per Id, non come quantità di record da saltare. Passa sempre 0 nella prima chiamata (a prescindere dalla direzione di ordinamento) e, nelle successive, il valore di NextOffset restituito dalla risposta precedente. Non costruire l'offset manualmente sommando le dimensioni delle pagine.