Ogni risposta di errore porta lo stesso envelope JSON, il codice di stato HTTP corrisponde alla semantica e la stringa di errore è abbastanza stabile da poterci basare la logica del client. Segnalate codici di stato imprevisti a support@tracepass.eu.
Envelope
json
{
"error": "Validation error",
"details": {
"fieldErrors": {
"model": ["Required"]
}
}
}error è sempre presente ed è una stringa stabile — basateci la logica del vostro client. details è opzionale; quando è presente, la sua forma dipende dall'errore specifico (messaggi per campo in fieldErrors per la convalida, numeri di piano/utilizzo per un'eccedenza, nome del ruolo / autorizzazione per un 403).
Codici di stato
| Stato | Quando | Nuovo tentativo? |
|---|---|---|
| 400 | Errore di convalida — il corpo o la query non hanno superato il controllo dello schema; oppure chiave di campo sconosciuta in un PATCH di passaporto. | No (correggere la richiesta) |
| 401 | Chiave API mancante o revocata, oppure sessione scaduta. | No (generare una nuova chiave / autenticarsi di nuovo) |
| 402 | Quota del piano superata quando il piano prevede una tariffa di eccedenza: `epcis_events_overage_required` all'acquisizione EPCIS, `measurements_overage_required` sulle misurazioni. Su Free, l'acquisizione EPCIS e le misurazioni restituiscono invece `epcis_events_hard_block` / `measurements_hard_block`. La creazione di un passaporto non restituisce mai 402 per il limite del piano: una bozza non occupa posti del piano e il limite si applica alla pubblicazione dalla dashboard. Restituito anche dalle scritture v1 che aggiungono o modificano contenuti quando i pagamenti non sono in regola (scaduti, non pagati o abbonamento annullato). Le letture continuano a funzionare, così come le verifiche di ambito, le segnalazioni di risposte errate, le esecuzioni del catalogo e le modifiche al profilo di conformità. | Eccedenza: sì, con `confirmOverage: true`. Blocco: no (upgrade). Pagamenti: no (prima regolarizzate i pagamenti) |
| 403 | Autorizzazione dello spazio di lavoro negata (es. credenziali solo portale-fornitore che tentano una scrittura v1). | No |
| 404 | La risorsa non esiste o si trova in un altro spazio di lavoro. | No |
| 409 | Conflitto. Nelle scritture di passaporti: il passaporto è archiviato (`passport_archived`); un campo di identità (GTIN, numero di serie, ecc.) è bloccato dopo la prima pubblicazione (`identifier_locked`, con i nomi dei campi bloccati in `keys`); oppure una race di scrittura concorrente (`concurrent_update` — ricaricare e riprovare). In ogni scrittura v1: una richiesta con la stessa Idempotency-Key è ancora in corso (`idempotency_key_in_use` — ritentate con la stessa chiave quando termina). Nella creazione di prodotto o passaporto: model duplicato, GTIN registrato a un tenant diverso, o collisione di numero di serie all'interno di un GTIN. | Per concurrent_update e idempotency_key_in_use: sì (ritentare). Altri: risolvere prima il conflitto |
| 410 | Il passaporto è scaduto: l'abbonamento è terminato e il periodo di tolleranza di 30 giorni è trascorso. Torna raggiungibile se l'abbonamento viene ripristinato. I passaporti archiviati restituiscono 404, non 410. | No |
| 413 | Payload troppo grande — riguarda i caricamenti di immagini multipart (limite di 5 MB). | No |
| 415 | Media type non supportato — caricamento di un'immagine che non è PNG / JPG / WebP, o di un file il cui contenuto non corrisponde al tipo dichiarato. | No |
| 422 | Idempotency-Key riutilizzata con un corpo della richiesta diverso; oppure, in un caricamento, lo scanner antivirus ha rilevato malware. | No (generare una chiave nuova; in un caricamento il file è rifiutato) |
| 423 | La risorsa è sospesa (solo nel visualizzatore pubblico del passaporto). | No |
| 429 | Limite di frequenza superato — scritture giornaliere o letture giornaliere di passaporti. | Sì (dopo la successiva mezzanotte UTC) |
| 500 | Errore del server non gestito. Siamo stati allertati. | Sì (con backoff) |
| 503 | Finestra di manutenzione o sovraccarico (restituisce Retry-After); oppure, in un caricamento, lo scanner antivirus è momentaneamente non disponibile — nulla viene archiviato senza controllo. | Sì (dopo Retry-After) |
Indicazioni sui nuovi tentativi
Per le righe “Sì” qui sopra: backoff esponenziale con jitter, limitato a sei tentativi. I nuovi tentativi aggressivi consumano il vostro budget di scrittura giornaliero senza beneficio. L'header Retry-After è impostato su ogni 503; il reset del limite di frequenza per 429 è sempre la successiva 00:00 UTC.
Stringhe di errore comuni
| Stringa di errore | Stato | Significato |
|---|---|---|
Validation error | 400 | Il controllo dello schema è fallito. details.fieldErrors contiene le motivazioni, raggruppate per campo. |
Invalid field key: <key> | 400 | PATCH .../fields/<key> ha referenziato una chiave non presente nel template del passaporto. |
No template found for category: <slug> | 400 | La categoria che avete inviato non è preconfigurata — verificate l'ortografia rispetto alla Buyer's Guide pubblica. |
A product with this model already exists for your company | 409 | Le stringhe model sono univoche all'interno di uno spazio di lavoro. Scegliete un model diverso o aggiornate il prodotto esistente. |
This GTIN is already registered by another company. Contact support if this is an error. | 409 | I GTIN sono univoci a livello globale tra i tenant — due aziende non possono possedere entrambe lo stesso GTIN. |
Serial number already exists for this GTIN | 409 | Scegliete un numero di serie diverso. All'interno di un singolo GTIN i numeri di serie devono essere univoci. |
passport_archived | 409 | Questo passaporto è stato archiviato. I passaporti archiviati sono permanentemente in sola lettura. Anche un passaporto contrassegnato per l'eliminazione è in sola lettura e restituisce lo stesso codice. |
identifier_locked | 409 | La richiesta modificherebbe, svuoterebbe o revocherebbe l'approvazione di un campo di identità (es. gtin, serialNumber) che ha già un valore approvato su un passaporto pubblicato. Un valore ancora in attesa di revisione può essere corretto e un campo vuoto compilato. L'array keys elenca i campi bloccati. |
concurrent_update | 409 | Un'altra scrittura ha modificato il passaporto mentre questa modifica veniva salvata. Ricaricate il passaporto e riprovate. |
idempotency_key_in_use | 409 | Una richiesta con la stessa Idempotency-Key è ancora in elaborazione. Attendete che termini, poi ritentate con la stessa chiave: riceverete il suo risultato. |
Idempotency-Key has already been used with a different request body. Use a new key for the new request, or reuse the original body. | 422 | Avete inviato la stessa chiave due volte con corpi diversi. Generate una chiave nuova. |
Subscription is past due — resolve billing to continue creating new content. Published passports remain accessible. | 402 | I pagamenti non sono in regola. Le scritture che aggiungono o modificano contenuti vengono rifiutate; tutte le letture continuano a funzionare e i passaporti pubblicati restano accessibili. Regolarizzate i pagamenti dalla dashboard. |
API rate limit: N writes/day via /api/v1. Currently X today; requested Y. Retry tomorrow (UTC) or upgrade your plan. | 429 | Budget di scrittura v1 giornaliero esaurito. Attendete o fate un upgrade. |
API rate limit: N passports/day read via /api/v1. Currently X today; requested Y. Retry tomorrow (UTC) or contact support for a bulk export. | 429 | Budget di lettura passaporti v1 giornaliero esaurito. Attendete, fate un upgrade, oppure usate l'esportazione massiva JSON-LD dalla dashboard. |
Passport not found | 404 | ID errato o spazio di lavoro errato. Verificate che la chiave API corrisponda allo spazio di lavoro che possiede il passaporto. |