PDF Blocks
Ouvrir la page

Rate limits et utilisation

Comment les requêtes sont décomptées de votre plan, à quoi ressemble la réponse 429 et la limite de taille d’une seule requête.

Tourné vers l’avenir. Le rate limiting, les plafonds d’utilisation et les réponses 402, 403 et 429 font partie du contrat de l’API mais ne sont pas encore appliqués. Cette page décrit leur comportement pour que vous puissiez construire un client qui y soit prêt. Aucun seuil chiffré n’est publié ici pour elles, parce qu’aucun n’est en vigueur. Les limites de taille des requêtes font exception : elles s’appliquent dès aujourd’hui, et la limite est publiée plus bas.

PDF Blocks est conçu pour se dégrader proprement sous la charge et pour garder votre utilisation visible. Cette page explique comment l’utilisation est comptabilisée, comment le rate limiting se manifeste et comment dimensionner vos requêtes.

Comment l’utilisation est comptabilisée

L’utilisation est comptabilisée par plan et suivie dans votre dashboard. Le dashboard fait foi pour ce que vous avez consommé sur votre plan, à la fois le nombre de documents traités et le nombre de requêtes effectuées. Consultez-le pour surveiller votre consommation et voir à quel point vous approchez du volume autorisé par votre plan.

Comme l’API est stateless, chaque requête est comptabilisée pour elle-même ; il n’y a ni session ni lot à rapprocher. Une action multi-documents comme une division compte quand même pour une seule requête.

Les rate limits et la réponse 429

Quand le rate limiting sera appliqué, les requêtes qui dépassent le volume autorisé par votre plan recevront 429 Too Many Requests et un corps problem+json. Un 429 est transitoire : la même requête réussira dès que vous ralentirez.

Construisez vos clients pour le gérer dès le premier jour :

  • Espacez vos tentatives de façon exponentielle. Sur un 429, attendez avant de réessayer et augmentez le délai à chaque 429 successif (en le doublant, par exemple) au lieu de réessayer immédiatement dans une boucle serrée.
  • Respectez Retry-After. Quand la réponse porte un en-tête Retry-After, attendez au moins ce délai avant de réessayer plutôt que d’appliquer le vôtre.
  • Ajoutez de l’aléatoire. Faites varier légèrement le délai au hasard pour que des workers parallèles ne réessaient pas tous au même instant.
  • Limitez les tentatives. Abandonnez après un nombre raisonnable d’essais et remontez l’échec plutôt que de réessayer indéfiniment.

La même stratégie d’espacement s’applique à la rare erreur serveur 5xx.

Limites de taille des requêtes

Chaque plan limite la taille d’un seul document en entrée : 5 MB sur Free, 10 MB sur tout autre plan (voir Tarifs). Une requête dont le corps dépasse cette limite est rejetée avec 413 Payload Too Large et renvoie un corps problem+json sans être traitée. Contrairement à un 429, un 413 ne réussira pas à la nouvelle tentative : envoyez un fichier plus petit, ou demandez-nous de relever la limite de votre compte si vous en avez régulièrement besoin.

Réponses liées à la facturation

Deux autres codes réservés concernent votre compte plutôt que la requête elle-même :

  • 402 Payment Required : une condition de facturation ou de quota sur votre plan. Réglez-la depuis le dashboard.
  • 403 Forbidden : votre clé est valide mais n’a pas le droit d’utiliser la ressource demandée.

Les deux figurent dans le catalogue des Erreurs, avec la forme complète de la réponse.