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.
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.
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. |
monthly-quota-exceeded | 429 | Hai superato il limite di richieste mensili per il tuo piano, e non è possibile addebitare richieste extra. Puoi migrare a un piano superiore o attendere il mese successivo per ripristinare la tua quota. |
daily-limit-exceeded | 429 | Hai superato il limite di richieste giornaliere per il tuo piano. Puoi migrare a un piano superiore o attendere il giorno successivo per ripristinare la tua quota. |
burst-limit-exceeded | 429 | Hai superato il limite di richieste al secondo per il tuo piano. Puoi migrare a un piano superiore o ridurre la frequenza delle tue richieste. |
unexpected-error | 500 | Si è verificato un errore imprevisto. Riprova più tardi o contatta il supporto. |