--- seo_title: Rate limit, quote di ops e limiti dei piani | EnConvert meta_desc: Quota mensile di ops, tetto di upload, conservazione degli artefatti e rate limit per piano, più il codice di stato che l'API restituisce quando superi un limite. keywords: rate limit api, quota mensile ops api, cosa conta come operazione api, errore 402 quota superata, header 429 rate limit, retry-after api riprova, dimensione massima file per piano, limite batch url api --- # Rate limit e quote EnConvert misura una cosa sola: l'operazione. Il tuo piano acquista un certo numero di operazioni al mese, più un tetto di upload, una finestra di conservazione e una dimensione di batch. Questa pagina spiega che cos'è una op, che cosa ottiene ogni piano e quale codice di stato torna indietro quando superi il limite. Due limiti si confondono facilmente. La quota mensile risponde `402`. Il limitatore di frequenza delle richieste su finestre brevi risponde `429`. Sono sistemi separati e nessuno dei due sostituisce l'altro. --- ## Che cosa conta come operazione Una op è un'unità di lavoro. Ogni endpoint addebita la stessa singola op per la stessa singola unità, senza moltiplicatori e senza contatori per endpoint. Nulla viene fatturato nemmeno in base al tempo di render: una pagina che impiega 30 secondi a renderizzare costa esattamente quanto una pagina che ne impiega due. L'unità in sé cambia da endpoint a endpoint, perché «un'unità di lavoro» significa una cosa per un singolo file e un'altra per un crawl: | Endpoint | Che cosa acquista una op | |----------|------------------| | [`POST /v1/convert/*`](/it/docs/endpoints/convert.md) | Una conversione. Il caricamento di un file è una op. Un batch di 20 URL è 20 ops. | | [`POST /v2/perceive`](/it/docs/endpoints/perceive.md) | Una lettura di URL. Un batch di 20 URL è 20 ops. Un cache hit viene addebitato come qualsiasi altra lettura. | | [`POST /v2/ingest`](/it/docs/endpoints/ingest.md) | Una pagina completata. Le pagine che non riescono a essere renderizzate e suddivise in chunk non vengono conteggiate. | | [`POST /v2/lookup`](/it/docs/coming-soon/lookup.md) | Una query, più una op per ogni risultato che l'API renderizza per te. I due costi si sommano di proposito. | | [`POST /v2/distill`](/it/docs/coming-soon/distill.md) | Un URL completato. | | [`POST /v2/discover`](/it/docs/coming-soon/discover.md) | Una chiamata, qualunque sia la dimensione del sito. | | [`POST /v2/watch`](/it/docs/coming-soon/watch.md) | Niente. I watcher costano zero ops. Sono invece limitati per numero. | Lookup, distill, discover e watch sono in beta privata: chiamabili già oggi, ma non annunciati e non disponibili in generale. Le regole di conteggio qui sopra valgono per loro esattamente così come sono scritte; consulta [In arrivo](/it/docs/coming-soon.md). Altre due regole valgono ovunque. Le ops vengono conteggiate al completamento, quindi una richiesta fallita non intacca la tua quota. E una richiesta a più unità viene verificata in anticipo: un batch di 40 URL viene confrontato con la quota residua prima che venga recuperato anche un solo URL, così viene rifiutato per intero anziché elaborato a metà. Le chiamate di sola lettura sono gratuite. Fare polling su un job, elencare i tuoi job di ingest o i tuoi watcher e scaricare un artefatto finito non consumano nulla. --- ## Piani Ogni numero qui sotto è applicato dall'API, non è un'aspirazione. La colonna slug è quella che vedi nelle risposte dell'API (per esempio il campo `tier` su un `413`); il nome è quello che vedi sulla [pagina dei prezzi](/it/pricing.md) e in fattura. | Piano | Slug | Ops al mese | Upload massimo | Conservazione artefatti | Limite batch | Eccedenza | |------|------|---------------|------------|--------------------|-------------|---------| | Founding | `free` | 500 | 5 MB | 1 ora | Batch non disponibile | Non disponibile | | Indie | `starter` | 3.000 | 15 MB | 7 giorni | 50 URL per batch | $0.02/op, attivabile | | Studio | `pro` | 15.000 | 50 MB | 7 giorni | 100 URL per batch | $0.02/op, attivabile | | Production | `business` | 50.000 | 150 MB | 30 giorni | 400 URL per batch | $0.02/op, attivabile | I limiti Enterprise vengono definiti per contratto anziché a partire da questa tabella. La quota Founding si esaurisce facilmente per sbaglio. 500 ops sono 500 pagine, e un solo crawl può prendersele tutte in una singola chiamata, quindi limita `max_pages` prima di puntare [ingest](/it/docs/endpoints/ingest.md) su un sito di documentazione. Le ops si azzerano all'inizio di ogni ciclo di fatturazione e non si accumulano. Il tetto di upload viene verificato sul conteggio esatto dei byte della parte caricata prima che inizi qualsiasi conversione, e un file la cui dimensione coincide esattamente con il tetto viene accettato. La conservazione è per quanto tempo un artefatto prodotto resta in storage; l'URL firmato che punta a quell'artefatto vive 15 minuti e può essere rifirmato dall'endpoint di stato finché la finestra di conservazione non si chiude, come spiegato in [URL firmati](/it/docs/concepts/signed-urls.md). ### Quote che non sono ops Due allocazioni stanno accanto al contatore delle ops e non attingono mai da esso. | Piano | Crediti AI al mese | Watcher attivi | |------|----------------------|-----------------| | Founding | $0 | Watch non disponibile | | Indie | $5 | 20 | | Studio | $15 | 100 | | Production | $40 | 500 | I crediti AI non usati si accumulano nel periodo successivo. Esaurirli non fa fallire una richiesta: l'estrazione tramite schema ricade sul risultato euristico e CSS e la chiamata va comunque a buon fine. I watcher sono uno slot che occupi, non un consumo, quindi un watcher inattivo non costa nulla e nemmeno uno impegnato. Il tetto riguarda quanti ne esistono contemporaneamente. --- ## Quando la quota mensile si esaurisce L'API risponde `402 Payment Required`, mai `429`, e il corpo ha la forma standard `{"detail": "..."}`. ```json { "detail": "Monthly operations limit reached (500/500). Upgrade your plan to continue." } ``` Su questo percorso esistono tre messaggi: | Messaggio | Condizione | |---------|-----------| | `Monthly operations limit reached ({used}/{limit}). Upgrade your plan to continue.` | Il contatore ha raggiunto la quota del piano. | | `This request needs {units} operations but only {remaining} of your {limit} monthly operations remain. Upgrade your plan to continue.` | Una richiesta batch o multi-URL è più grande di ciò che resta. L'intera richiesta viene rifiutata. | | `No active billing period found for this project. Contact support to restore your subscription.` | Non esiste alcun periodo di utilizzo e non è stato possibile crearne uno. Il controllo fallisce in modo restrittivo anziché concedere una op gratuita. | Quando il contatore raggiunge il 100 percento per la prima volta, il proprietario del progetto riceve anche un'email, al massimo una ogni 24 ore. ### Eccedenza L'eccedenza è disponibile su tutti i piani a pagamento, a $0.02 per operazione, ed è disattivata per impostazione predefinita. Attivala e le richieste oltre la tua quota continuano a funzionare, oltre le 3.000 su Indie, le 15.000 su Studio e le 50.000 su Production, con le ops in più fatturate a quella tariffa. Lasciala disattivata e la quota è un blocco netto fino al ciclo successivo, ed è proprio questo il punto: un loop impazzito non può costarti denaro in silenzio. Sul piano gratuito Founding il blocco netto è l'unico comportamento; Enterprise segue il contratto. ### Sapere a che punto sei Per questo non esiste alcun header. Le risposte andate a buon fine non portano alcun conteggio delle ops residue né campi di utilizzo di alcun tipo, quindi gli unici modi per conoscere la tua posizione sono la dashboard e la contabilità delle tue richieste. Metti in conto il `402` invece di aspettare un avviso. --- ## Rate limit sulle richieste Oltre alla quota mensile, le richieste sono limitate anche su finestre brevi, così un singolo progetto non può soffocare gli altri. Tre finestre corrono insieme: al minuto, all'ora e al giorno. I limiti crescono con il tuo piano. I numeri esatti per ciascuna finestra non sono pubblicati qui. Leggili invece dalla risposta: un rifiuto ti dice quale limite è scattato e quanto attendere, ed è quello il valore che l'API sta davvero applicando. Ciò che è fisso è il comportamento: - I limiti si applicano per progetto, non per chiave API, quindi ruotare le chiavi non azzera una finestra. - Il traffico pubblico (`pk_`) e quello privato (`sk_`) usano contatori separati, e il traffico con chiave pubblica ha in più un tetto per IP sotto la finestra di progetto. - Sono limitate solo le richieste `POST` che fanno lavoro: gli endpoint di conversione, gli endpoint V2 e l'emissione dei token. Ogni `GET` è esente, quindi il polling dello stato e i download non fanno scattare nulla. Un rifiuto è `429 Too Many Requests`: ```json { "detail": "Rate limit exceeded. Please slow down and retry shortly." } ``` Porta con sé quattro header: | Header | Significato | |--------|-------------| | `RateLimit-Limit` | Richieste consentite nella finestra che è scattata. | | `RateLimit-Remaining` | Richieste rimaste in quella finestra, `0` su un rifiuto. | | `RateLimit-Reset` | Secondi mancanti all'azzeramento di quella finestra. | | `Retry-After` | Lo stesso numero di `RateLimit-Reset`. Attendi questo tempo, poi riprova. |
Questi header compaiono solo sul 429. Una risposta andata a buon fine non porta alcun header RateLimit-*, e l'API non invia mai la grafia X-RateLimit-*. Non costruire un client che legga il proprio budget da un 200.
Sia `RateLimit-Reset` sia `Retry-After` sono secondi interi e non scendono mai sotto `1`. Attendere il numero di secondi indicato e riprovare una volta è l'intera procedura di ripristino. --- ## Limiti che non sono 429 La maggior parte delle risposte di limite non arriva dal rate limiter. Questi sono quelli in cui si incappa davvero. ### 413: il file caricato è troppo grande Superare il tetto di upload del tuo piano restituisce `413` con un oggetto strutturato come valore di `detail`. Leggi `body.detail.max_size`, non `body.max_size`. ```json { "detail": { "error": "File too large", "file_size": 10485760, "max_size": 5242880, "tier": "free", "key_type": "private" } } ``` | Campo | Descrizione | |-------|-------------| | `error` | Sempre `"File too large"`. | | `file_size` | La dimensione del file caricato in byte. | | `max_size` | Il tetto del tuo piano in byte. | | `tier` | Lo slug del tuo piano, con fallback a `"free"` quando nessun piano viene risolto. | | `key_type` | `"private"`, `"public"` o `"dashboard"`, con fallback a `"unknown"`. | `POST /v2/ingest/files` è l'eccezione: risponde `413` con una semplice stringa, `File '{filename}' exceeds the {max_size}-byte limit.` ### 403: una funzionalità batch o V1 che il tuo piano non ha | Messaggio | Condizione | |---------|-----------| | `Batch processing is not available on your current plan. Please upgrade to access this feature.` | Più di un URL inviato su un piano senza quota di batch. | | `Batch size {N} exceeds your plan's limit of {M} URLs per batch.` | Il numero di URL supera il limite di batch del piano. Dividi l'elenco e invialo in più parti. | | `Async processing is not available on your current plan. Please upgrade to access this feature.` | `async_mode=true` senza accesso asincrono. | | `Webhook callbacks is not available on your current plan. Please upgrade to access this feature.` | `callback_url` senza accesso ai webhook. | | `ZIP output bundling is not available on your current plan. Please upgrade to access this feature.` | `output_format: true` senza accesso all'output ZIP. Il campo della richiesta è un booleano; `"zip"` e `"individual"` sono i valori che tornano nella risposta. | | `Basic authentication, cookies & custom headers is not available on your current plan. Please upgrade to access this feature.` | `auth`, `cookies` o `headers` senza quell'accesso. | | `Website crawling is not available on your current plan. Please upgrade to access this feature.` | `website-to-pdf` o `website-to-screenshot` su un piano senza accesso al crawl. | | `Full website crawling requires a Studio plan or higher. Your plan supports sitemap-based crawling only.` | `crawl_mode: "full"` su un piano che scopre gli URL solo da `sitemap.xml`. | ### 402: un endpoint V2 disattivato, o un altro tetto I controlli sugli endpoint V2 rispondono `402` anziché `403`, ed è l'unica asimmetria di questo schema che vale la pena memorizzare: | Messaggio | Condizione | |---------|-----------| | `{Feature} is not available on your current plan. Upgrade to a V2-inclusive plan to access this endpoint.` | L'endpoint è disattivato per il tuo piano. | | `Active watcher limit reached ({active_count}/{limit}). Delete an existing watcher or upgrade your plan to add more.` | Il progetto ha già il numero massimo di watcher attivi. | | `Storage limit reached. Delete files or upgrade your storage plan to continue.` | La quota dell'add-on di storage è piena. | ### 503: è il servizio a essere occupato, non tu `The conversion service is at capacity. Please retry shortly.` (inviato con `Retry-After: 30`) e `Server is at capacity. Please retry shortly.` (inviato con `Retry-After: 10`) sono controlli di capacità dalla nostra parte. Non vengono conteggiati a tuo carico e non sono rate limiting. Leggi `Retry-After` invece di dare per scontato che una sola attesa valga per entrambi. --- ## Pagine correlate - [Errori](/it/docs/reference/errors.md) contiene ogni codice di stato e messaggio che l'API può restituire. - [Elaborazione batch](/it/docs/guides/batch-processing.md) spiega come il limite di batch interagisce con l'output ZIP e il polling. - [Ingestione dei file](/it/docs/guides/file-ingestion.md) copre i percorsi di upload a cui si applica il tetto di dimensione. - [URL firmati](/it/docs/concepts/signed-urls.md) copre la finestra di download di 15 minuti che sta dentro la tua finestra di conservazione.