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, mentre eventuali errori sono indicati dalla proprietà error e accompagnati da un messaggio descrittivo nella proprietà message.

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

Errori comuni

Ogni errore restituito dall’API include un messaggio di errore e un codice di errore interno.

Codice interno	Status	Soluzione
`bad-request`	400	La richiesta non è valida. Controlla i parametri e il formato della richiesta.
`missing-api-key`	401	La chiave API non è stata fornita. Assicurati di includere la chiave API nell'header della richiesta sotto la voce `x-api-key`.
`invalid-api-key`	401	La chiave API fornita non è valida. Controlla che la chiave sia corretta e attiva.
`no-active-subscription`	403	Non hai una sottoscrizione attiva. Controlla la tua sottoscrizione dalla sezione Profilo › Fatturazione.
`incomplete-subscription`	403	L'acquisto della tua sottoscrizione non è stato ancora completato, vai al portale di fatturazione per completarlo.
`past-due-subscription`	403	La tua sottoscrizione è scaduta. Controlla la tua sottoscrizione dalla sezione Profilo › Fatturazione.
`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.
`unexpected-error`	500	Si è verificato un errore imprevisto. Riprova più tardi o contatta il supporto.