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:

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.

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 e in fattura.

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 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.

Quote che non sono ops#

Due allocazioni stanno accanto al contatore delle ops e non attingono mai da esso.

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": "..."}.

{
    "detail": "Monthly operations limit reached (500/500). Upgrade your plan to continue."
}

Su questo percorso esistono tre messaggi:

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:

{
    "detail": "Rate limit exceeded. Please slow down and retry shortly."
}

Porta con sé quattro header:

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.

{
    "detail": {
        "error": "File too large",
        "file_size": 10485760,
        "max_size": 5242880,
        "tier": "free",
        "key_type": "private"
    }
}

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#

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:

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 contiene ogni codice di stato e messaggio che l'API può restituire.
• Elaborazione batch spiega come il limite di batch interagisce con l'output ZIP e il polling.
• Ingestione dei file copre i percorsi di upload a cui si applica il tetto di dimensione.
• URL firmati copre la finestra di download di 15 minuti che sta dentro la tua finestra di conservazione.