Risposte ed errori
Le risposte dell’API sono sempre in formato JSON e includono informazioni sul risultato della richiesta sia nel corpo della risposta che negli header HTTP.
Il prodotto della richiesta è incluso nella proprietà data della risposta JSON. In caso di errore, success è false, code identifica l'errore e message può includere una descrizione.
Envelope<QueryResponse>: success: boolean timestamp: number
code: string message: string?
data: QueryResponse | nullPuoi verificare in tempo reale il comportamento dell'API tramite il playground. Le richieste effettuate dal playground non sono soggette a quota mensile.
Header di risposta
Oltre al corpo della risposta, l'API restituisce anche header HTTP che forniscono informazioni operative sulla richiesta, come identificatori di tracciamento, limiti di rate limit e addebiti per overage. Questi header ti permettono di monitorare e gestire efficacemente le tue integrazioni con l'API.
| Header | Descrizione |
|---|---|
CW-Trace-Id | Identificatore univoco per la richiesta. Usalo per correlare i log o per il supporto. |
CW-Billable-Overage | true o false. Indica se la richiesta è stata conteggiata come overage a pagamento. |
CW-Rate-Limited-By | Presente quando bloccato da un rate limiter. Può essere burst, daily, o monthly. |
CW-Rate-Limited-Until | Timestamp in millisecondi quando il rate limit si resetterà, se applicabile. |
Retry-After | Header HTTP standard con secondi fino al reset del rate limit, se applicabile. |
Questi header ti permettono di correlare i log tramite CW-Trace-Id, monitorare gli overage a pagamento tramite CW-Billable-Overage, e implementare una logica di retry con backoff esponenziale tramite CW-Rate-Limited-* e Retry-After.
Esempio di risposta di successo
Di seguito trovi un esempio di risposta JSON restituita dall'API in caso di successo.
Alimentazione e propulsione
vehicle.engine.energySources contiene una o più fonti energetiche. I valori standard sono:
| Valore | Significato |
|---|---|
petrol | Benzina |
diesel | Gasolio |
electricity | Energia elettrica |
lpg | GPL |
methane | Metano |
hydrogen | Idrogeno |
lpg-or-methane | GPL o metano non distinguibili |
other | Altra fonte energetica |
Una fonte non compresa nell'elenco è rappresentata da un oggetto con un valore canonico e un'etichetta leggibile:
vehicle.engine.powertrain descrive il sistema di propulsione indipendentemente dalle fonti energetiche:
| Valore | Significato |
|---|---|
combustion | Motore a combustione |
hybrid | Sistema ibrido |
electric | Sistema elettrico |
fuel-cell | Sistema a celle a combustibile |
other | Altro sistema di propulsione |
Classe ambientale
emissions.euroClass è un oggetto composto da:
| Campo | Tipo | Descrizione |
|---|---|---|
stage | number | Livello Euro numerico. |
phase | string | Fase della normativa, quando disponibile. |
regime | string | Regime applicabile: light-duty, heavy-duty oppure motorcycle. |
phase e regime sono omessi quando non disponibili.
Errori comuni
Ogni errore restituito dall’API include un messaggio di errore e un codice di errore interno. Consulta la pagina Errori per l’elenco completo.