InfoTarga

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.

1
Envelope<QueryResponse>:
2
    success: boolean
3
    timestamp: number
4

5
    code: string
6
    message: string?
7

8
    data: QueryResponse | null

Puoi 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`	Indica il limite che ha bloccato la richiesta: `usage` (slot di utilizzo), `burst` (slot di picco) o `concurrency` (slot simultanei). Se più limiti bloccano la richiesta, la priorità è slot di utilizzo, slot di picco, slot simultanei.
`CW-Rate-Limited-Until`	Orario suggerito per riprovare, come timestamp Unix in millisecondi. Assente quando anche il limite di richieste simultanee blocca la richiesta. Non riserva capacità né garantisce che il tentativo successivo venga accettato.
`Retry-After`	Attesa minima suggerita prima di riprovare, in secondi interi. Tiene conto di quando gli slot di utilizzo e di picco tornano disponibili. Per il solo limite di slot simultanei, l’attesa suggerita è un secondo.

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.

Risposta JSON

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:

Fonte energetica

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

I dati tecnici del motore possono includere:

Campo	Significato
`powerKw`	Potenza in kilowatt.
`powerMetricHp`	Potenza in cavalli metrici.
`fiscalHp`	Potenza fiscale.
`displacementCc`	Cilindrata in centimetri cubici.

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.