Errori
In caso di errore, l'API restituisce un codice HTTP appropriato e un corpo JSON con questa struttura:
| Campo | Tipo | Descrizione |
|---|---|---|
success | false | Indica che la richiesta non è stata completata. |
code | string | Codice stabile dell'errore. |
message | string | Descrizione dell'errore. |
data | null | Nessun risultato disponibile. |
timestamp | number | Data e ora della risposta, come timestamp Unix in millisecondi. |
Per gestire gli errori nell'integrazione, utilizza lo status HTTP e il valore di code.
Errori della richiesta
| Codice | Status | Significato |
|---|---|---|
bad-request | 400 | Corpo JSON non valido, campi obbligatori assenti, servizi non validi o duplicati. |
invalid-plate-format | 400 | Formato della targa non valido per la tipologia di veicolo indicata. |
missing-api-key | 401 | Header x-api-key assente. |
invalid-api-key | 401 | Chiave API non valida o non attiva. |
Sottoscrizione
| Codice | Status | Significato |
|---|---|---|
no-active-subscription | 403 | Nessuna sottoscrizione attiva per il servizio. |
incomplete-subscription | 403 | Attivazione della sottoscrizione non completata. |
past-due-subscription | 403 | Pagamento della sottoscrizione scaduto. |
La sottoscrizione può essere gestita dalla sezione Profilo › Fatturazione.
Limiti di utilizzo
| Codice | Status | Significato |
|---|---|---|
rate-limit-exceeded | 429 | Un limite di utilizzo ha bloccato la richiesta. Controlla CW-Rate-Limited-By e attendi almeno il numero di secondi indicato da Retry-After prima di riprovare. |
Le risposte con status 429 possono includere:
| Header | Descrizione |
|---|---|
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. |
Errori interni
| Codice | Status | Significato |
|---|---|---|
internal-server-error | 500 | Errore interno durante l'elaborazione della richiesta. |
unexpected-error | 500 | Errore imprevisto. |
L'header CW-Trace-Id, quando presente, identifica la richiesta e può essere comunicato al supporto.