--- title: Errori e limiti di frequenza description: "Riferimento: codici di stato HTTP, forma dell'envelope di errore, limiti giornalieri sul livello gratuito, indicazioni sui nuovi tentativi." canonical: "https://www.tracepass.eu/it/docs/errors" locale: it source: "https://www.tracepass.eu/it/docs/errors" --- # Errori e limiti di frequenza > Riferimento: codici di stato HTTP, forma dell'envelope di errore, limiti giornalieri sul livello gratuito, indicazioni sui nuovi tentativi. 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. L'elenco qui sotto è esaustivo — se incontrate qualcosa che non vi è incluso, segnalatelo a [support@tracepass.eu](mailto: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 (un risultato Zod appiattito 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 DPP esaurita in una chiamata di creazione passaporto. Ritentare con \`confirmOverage: true\` se il piano supporta l'eccedenza. Si attiva anche quando è richiesto un abbonamento attivo ma è past\_due/canceled. | Sì, con \`confirmOverage: true\` | | 403 | Plan-gate (es. API v1 su un piano Free) oppure autorizzazione dello spazio di lavoro negata. | No | | 404 | La risorsa non esiste o si trova in un altro spazio di lavoro. | No | | 409 | Conflitto — model duplicato su un prodotto, GTIN registrato a un tenant diverso, collisione di numero di serie all'interno di un GTIN. | A volte (risolvere il conflitto, poi ritentare) | | 410 | La risorsa è stata rimossa in modo permanente (raro; riguarda soprattutto gli URL pubblici dei passaporti dopo l'archiviazione). | 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. | No | | 422 | Idempotency-Key riutilizzata con un corpo della richiesta diverso. | No (generare una chiave nuova) | | 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. | Sì (dopo Retry-After) | ## Indicazioni sui nuovi tentativi Per le righe “Sì” qui sopra: backoff esponenziale con jitter, limitato a sei tentativi. Non accettiamo nuovi tentativi più aggressivi di uno al secondo su un singolo endpoint — qualcosa di più veloce comunque non raggiungerà il database (il rate limiter in memoria lo rifiuta), ma consumerete il vostro budget di scrittura giornaliero. L'header`Retry-After` è impostato su ogni `503`; il reset del limite di frequenza per `429` è sempre la successiva 00:00 UTC. **Tip —** Abbinate ogni nuovo tentativo alla stessa `Idempotency-Key` dell'originale — è così che evitate di creare un passaporto in doppio quando la scrittura originale è andata a buon fine ma la risposta è andata persa. ## Stringhe di errore comuni | Stringa di errore | Stato | Significato | | --------------------------------------------------------------------------------------------------------------------------------------------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Validation error | 400 | Il controllo dello schema è fallito. details.fieldErrors porta le motivazioni per ogni campo (Zod flatten()). | | Invalid field key: | 400 | PATCH .../fields/ ha referenziato una chiave non presente nel template del passaporto. | | No template found for category: | 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. | | 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. | | overage\_required | 402 | Quota DPP esaurita. Il corpo porta planLimit + currentUsage + extraPriceCents. Ritentare con \`confirmOverage: true\` per accettare l'addebito per passaporto. | | 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. | Non modifichiamo la formulazione di una stringa di errore in una versione minore. Se ci serve una stringa più chiara, aggiungiamo un campo `code` affiancato nell'envelope (numerico, con namespace) e lo annunciamo nel changelog normativo. Le stringhe stabili vi permettono di basare la logica del client con fiducia.