Guida al prodotto e alle API

Errori

Gli errori vengono restituiti come problem+json secondo RFC 9457. Ogni risposta contiene correlationId: indicalo quando contatti l'assistenza.

Stato	Significato	Cosa fare
`401`	Chiave mancante o non valida	Controlla l'intestazione X-PDFgine-Key e che la chiave non sia stata revocata.
`402`	Quota esaurita	Passa a un piano superiore o attendi il rinnovo del periodo.
`404`	Modello o documento non trovato	Verifica il codice del modello e che esista una revisione pubblicata.
`429`	Limite di frequenza superato	Attendi il numero di secondi indicato in Retry-After, poi riprova.

I limiti di frequenza dipendono dal piano

I limiti al minuto e all'ora degli endpoint di generazione sono per TENANT e dipendono dal piano, come mostra la tabella. Poiché il conteggio è per tenant e non per chiave, una seconda chiave API non aumenta il limite. Una risposta 429 indica la finestra raggiunta nell'intestazione X-PDFgine-RateLimit-Scope: tenant-api, tenant-render-minute o tenant-render-hour. Per processi in blocco, invia fino a 100 documenti in una richiesta /document-batches anziché un documento per richiesta.

La risposta a quota esaurita

HTTP/1.1 402 Payment Required
X-PDFgine-Quota-Remaining: 0
X-PDFgine-Metering-Basis: pdf-equivalent

{
  "title": "Quota di pagine superata",
  "status": 402,
  "detail": "Il tuo piano ha esaurito la quota di pagine disponibile.",
  "correlationId": "114249cb1dbc52a29026ab2eca5c4b72"
}

Retry-After e la finestra

Si applicano due limiti, uno dopo l'altro. Il primo protegge il servizio e conta per credenziale: 30 richieste per finestra senza chiave, 120 con una chiave, in una finestra di 60 secondi. Il secondo dipende dal piano e conta per tenant.

Piano	Documenti / minuto	Documenti / ora
Gratuito	15	150
Go	30	300
Pro	60	600
Max	300	3.000

HTTP 429

HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-PDFgine-RateLimit-Scope: tenant-render-minute

{
  "title": "Too many requests",
  "status": 429,
  "detail": "The request limit was exceeded. Please try again later.",
  "correlationId": "505aac87e234a7b4669e6203ac7ffcd5"
}

La finestra è fissa, non mobile: si apre alla prima richiesta e tutte le richieste al suo interno consumano lo stesso limite, poi il conteggio si azzera. Retry-After indica i secondi rimasti nella finestra: basta attendere quel tempo; riprovare prima causa solo un altro rifiuto.

Gli errori più comuni

Un 4xx ripetuto senza modifiche fallisce ancora. Indica una richiesta errata, non un servizio occupato; solo 429 e 5xx meritano un nuovo tentativo.
Con 429 la risposta include già Retry-After. Stimare da soli l'attesa fa perdere tempo oppure porta direttamente a un altro rifiuto.
402 non è un guasto per cui svegliare qualcuno alle tre di notte. Significa che la quota mensile è esaurita: controlla X-PDFgine-Quota-Remaining e passa a un piano superiore prima che accada.
410 su un download non indica un file perso. La conservazione è terminata: il documento è stato prodotto, conteggiato e poi rimosso secondo i tempi del piano.
Registrare solo il codice di stato rende una richiesta di assistenza un gioco a indovinelli. Registra anche correlationId: basta quel valore per trovare la richiesta.