Errori e limiti di frequenza

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.

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'headerRetry-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: <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.
`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 codeaffiancato nell'envelope (numerico, con namespace) e lo annunciamo nel changelog normativo. Le stringhe stabili vi permettono di basare la logica del client con fiducia.