Limites de débit et quotas#

EnConvert ne mesure qu'une seule chose : l'opération. Votre plan achète un nombre d'opérations par mois, plus un plafond d'envoi, une fenêtre de rétention et une taille de lot. Cette page dit ce qu'est une op, ce que reçoit chaque plan, et quel code de statut revient quand vous dépassez.

Deux limites se confondent facilement. L'allocation mensuelle répond 402. Le limiteur de débit des requêtes sur fenêtre courte répond 429. Ce sont deux systèmes distincts, et aucun ne remplace l'autre.

Ce qui compte comme une opération#

Une op, c'est une unité de travail. Chaque endpoint facture la même op unique pour la même unité, sans multiplicateurs ni compteurs par endpoint. Rien n'est facturé au temps de rendu non plus : une page qui met 30 secondes à se rendre coûte exactement ce que coûte une page qui en met deux.

L'unité elle-même diffère selon l'endpoint, car « une unité de travail » ne signifie pas la même chose pour un fichier isolé que pour un crawl :

Lookup, distill, discover et watch sont en bêta privée : appelables aujourd'hui, mais ni annoncés ni en disponibilité générale. Les règles de décompte ci-dessus s'appliquent à eux telles quelles ; voir Bientôt disponible.

Deux autres règles s'appliquent partout. Les ops sont comptées à l'aboutissement : une requête en échec n'entame donc pas votre allocation. Et une requête multi-unités est vérifiée au préalable : un lot de 40 URL est mesuré par rapport à votre allocation restante avant qu'aucune URL ne soit récupérée, si bien qu'il est rejeté en entier plutôt que traité à moitié.

Les appels en lecture seule sont gratuits. Interroger une tâche, lister vos tâches d'ingestion ou vos watchers, et télécharger un artefact terminé ne consomment rien.

Plans#

Chaque chiffre ci-dessous est appliqué par l'API, ce ne sont pas des ordres de grandeur. La colonne slug est ce que vous voyez dans les réponses de l'API (par exemple le champ tier sur un 413) ; le nom est ce que vous voyez sur la page tarifaire et sur une facture.

Les limites Enterprise sont définies par contrat plutôt que d'après ce tableau.

L'allocation Founding se dépense facilement par accident. 500 ops, c'est 500 pages, et un seul crawl peut toutes les prendre en un unique appel : plafonnez donc max_pages avant de pointer ingest vers un site de documentation.

Les ops sont remises à zéro au début de chaque cycle de facturation et ne sont pas reportées. Le plafond d'envoi est vérifié par rapport au nombre exact d'octets de la partie envoyée avant que la moindre conversion ne démarre, et un fichier dont la taille est exactement celle du plafond est accepté. La rétention, c'est la durée pendant laquelle un artefact produit reste dans le stockage ; l'URL signée qui pointe vers lui vit 15 minutes et peut être régénérée depuis l'endpoint de statut jusqu'à la fermeture de la fenêtre de rétention, ce que couvre URLs signées.

Des allocations qui ne sont pas des ops#

Deux allocations coexistent avec le compteur d'ops et n'y puisent jamais.

Les crédits IA non utilisés sont reportés sur la période suivante. Les épuiser ne fait pas échouer une requête : l'extraction de schéma se rabat sur son résultat heuristique et CSS, et l'appel aboutit quand même. Les watchers sont un emplacement que vous occupez plutôt qu'une consommation : un watcher inactif ne coûte rien, et un watcher occupé non plus. Le plafond porte sur le nombre de watchers qui existent simultanément.

Quand l'allocation mensuelle est épuisée#

L'API répond 402 Payment Required, jamais 429, et le corps a la forme standard {"detail": "..."}.

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

Trois messages existent sur ce chemin :

Lorsque le compteur atteint 100 pour cent pour la première fois, le propriétaire du projet reçoit également un email, au plus un toutes les 24 heures.

Dépassement#

Le dépassement est disponible sur tous les plans payants, à $0.02 par opération, et il est désactivé par défaut. Activez-le et les requêtes au-delà de votre allocation continuent de fonctionner, au-delà de 3 000 sur Indie, 15 000 sur Studio et 50 000 sur Production, les ops supplémentaires étant facturées à ce tarif. Laissez-le désactivé et l'allocation est un arrêt net jusqu'au cycle suivant, et c'est bien l'intérêt : une boucle emballée ne peut pas vous coûter de l'argent en silence. Sur le plan gratuit Founding, l'arrêt net est le seul comportement ; Enterprise relève du contrat.

Savoir où vous en êtes#

Il n'existe aucun en-tête pour cela. Les réponses réussies ne portent aucun décompte d'ops restantes ni aucun champ d'utilisation, quel qu'il soit : les seuls moyens de connaître votre position sont le tableau de bord et votre propre comptabilité des requêtes. Anticipez la 402 plutôt que d'attendre d'être averti.

Limites de débit des requêtes#

Indépendamment de l'allocation mensuelle, les requêtes sont aussi limitées sur des fenêtres courtes, pour qu'un projet ne puisse pas évincer les autres. Trois fenêtres tournent en même temps : par minute, par heure et par jour. Les limites évoluent avec votre plan.

Les chiffres exacts par fenêtre ne sont pas publiés ici. Lisez-les plutôt dans la réponse : un rejet vous indique la limite qui s'est déclenchée et combien de temps attendre, et c'est bien cette valeur que l'API applique.

Ce qui est fixe, c'est le comportement :

• Les limites s'appliquent par projet, pas par clé API : faire tourner les clés ne réinitialise donc pas une fenêtre.
• Le trafic public (pk_) et le trafic privé (sk_) utilisent des compteurs distincts, et le trafic par clé publique porte un plafond par IP supplémentaire sous la fenêtre du projet.
• Seules les requêtes POST qui font du travail sont limitées : les endpoints de conversion, les endpoints V2 et l'émission de jetons. Chaque GET est exempté : l'interrogation de statut et les téléchargements ne déclenchent donc rien.

Un rejet est un 429 Too Many Requests :

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

Il porte quatre en-têtes :

RateLimit-Reset et Retry-After sont tous deux exprimés en secondes entières et ne descendent jamais en dessous de 1. Attendre le nombre de secondes indiqué et réessayer une fois, c'est toute la procédure de récupération.

Les limites qui ne sont pas des 429#

La plupart des réponses de limite ne viennent pas du limiteur de débit. Voici celles que l'on rencontre.

413 : l'envoi est trop volumineux#

Dépasser le plafond d'envoi de votre plan renvoie un 413 avec un objet structuré comme valeur de detail. Lisez body.detail.max_size, pas body.max_size.

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

POST /v2/ingest/files fait exception : il répond 413 avec une simple chaîne de caractères, File '{filename}' exceeds the {max_size}-byte limit.

403 : une fonctionnalité de lot ou V1 que votre plan n'a pas#

402 : un endpoint V2 désactivé, ou un autre plafond#

Les contrôles d'accès aux endpoints V2 répondent 402 plutôt que 403, la seule asymétrie de ce schéma qui mérite d'être retenue :

503 : c'est le service qui est occupé, pas vous#

The conversion service is at capacity. Please retry shortly. (envoyé avec Retry-After: 30) et Server is at capacity. Please retry shortly. (envoyé avec Retry-After: 10) sont des limites de capacité de notre côté. Elles ne vous sont pas décomptées et ne relèvent pas de la limitation de débit. Lisez Retry-After plutôt que de supposer qu'un seul délai d'attente couvre les deux.

Pages liées#

• Erreurs répertorie tous les codes de statut et messages que l'API peut renvoyer.
• Traitement par lot explique comment la limite de lot interagit avec la sortie ZIP et l'interrogation de statut.
• Ingestion de fichiers couvre les chemins d'envoi auxquels s'applique le plafond de taille.
• URLs signées couvre la fenêtre de téléchargement de 15 minutes qui se situe à l'intérieur de votre fenêtre de rétention.