Risposte ed errori
Codici HTTP, motivi del widget, cache.
Le risposte usano i codici HTTP standard. Il corpo degli errori è JSON: {"detail": "…"}. Ogni risposta porta un'intestazione X-Request-ID: citatela quando ci scrivete per un problema.
API dati
| Codice | Quando | Cosa fare |
|---|---|---|
200 | Tutto bene | — |
400 | Parametri mancanti o non validi (es. format sconosciuto, manca brand o mpn) | Correggere la chiamata |
401 | Chiave assente, non valida o disattivata | Verificare l'intestazione X-API-Key; rigenerare la chiave dall'area clienti |
403 | Prodotto o brand fuori dal perimetro del contratto; indirizzo IP non autorizzato; chiave di un servizio JS Script usata per i dati | Controllare il perimetro nell'area clienti o scriverci |
404 | Prodotto non trovato o non ancora pubblicabile; nessuna immagine/documento per il prodotto | Il prodotto può arrivare in seguito: riprovare, o segnalarcelo |
409 | brand + MPN corrispondono a più prodotti: il corpo elenca gli EAN candidati | Richiamare per EAN |
429 | Superato il limite di richieste al minuto (X-RateLimit-Remaining: 0) | Attendere il minuto successivo; per carichi iniziali chiedere un limite più alto |
500 | Errore nostro; il corpo contiene request_id | Scriverci con il request_id |
503 | Verifica temporaneamente non disponibile | Riprovare dopo qualche secondo |
JS Script
Il widget non mostra mai errori ai visitatori: in ogni caso di problema il contenitore resta vuoto e l'evento cs:rendered arriva con found: false e reason con il motivo:
| Motivo | Significato |
|---|---|
not_found | Prodotto non in catalogo o non ancora pubblicabile |
ambiguous | brand + MPN corrispondono a più prodotti: usare l'EAN |
missing_identifier | Né GTIN né brand + MPN nella chiamata |
out_of_scope | Prodotto fuori dal perimetro del contratto |
Se il server rifiuta lo shop (sconosciuto, disattivato) o il dominio chiamante non è tra quelli autorizzati, la risposta HTTP è 403 e il widget la tratta come "nessun contenuto". Durante lo sviluppo controllate la console del browser e la pagina Integrazione dell'area clienti (domini autorizzati).
Cache
I contenuti del widget sono serviti con cache privata di pochi minuti e i vocabolari con cache di qualche ora: una scheda aggiornata compare entro pochi minuti. Le immagini hanno cache lunga nei browser: se sostituiamo una foto, chi l'ha già vista può continuare a vedere quella vecchia finché il suo browser non la ricarica.