Guide du produit et de l’API

Erreurs

Les erreurs sont renvoyées au format problem+json conforme à RFC 9457. Chaque réponse contient correlationId ; communiquez-le à l’assistance.

État	Signification	Marche à suivre
`401`	Clé absente ou invalide	Vérifiez l’en-tête X-PDFgine-Key et assurez-vous que la clé n’a pas été révoquée.
`402`	Quota épuisé	Passez à une offre supérieure ou attendez le renouvellement de la période.
`404`	Modèle ou document introuvable	Vérifiez le code du modèle et l’existence d’une révision publiée.
`429`	Limite de débit dépassée	Attendez le nombre de secondes indiqué dans Retry-After, puis réessayez.

Les limites de débit dépendent de l’offre

Les limites par minute et par heure des points de terminaison de génération sont définies par ORGANISATION et dépendent de votre offre ; elles figurent ci-dessous. Comme elles comptent par organisation plutôt que par clé, ajouter une seconde clé API ne les augmente pas. Une réponse 429 indique la fenêtre atteinte dans l’en-tête X-PDFgine-RateLimit-Scope : tenant-api, tenant-render-minute ou tenant-render-hour. Pour les lots, envoyez jusqu’à 100 documents dans une requête /document-batches plutôt qu’un document par requête.

La réponse lorsque le quota est épuisé

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

{
  "title": "Quota de pages dépassé",
  "status": 402,
  "detail": "Votre offre a épuisé son quota de pages disponible.",
  "correlationId": "114249cb1dbc52a29026ab2eca5c4b72"
}

Retry-After et la fenêtre

Deux limites s’appliquent successivement. La première protège le service et compte par identifiant : 30 requêtes par fenêtre sans clé, 120 avec une clé, sur une fenêtre de 60 secondes. La seconde dépend de votre offre et compte par organisation.

Offre	Documents / minute	Documents / heure
Gratuit	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 fenêtre est fixe, et non glissante : elle s’ouvre à la première requête, toutes les requêtes qu’elle contient utilisent le même quota, puis le compteur se réinitialise. Retry-After indique les secondes restantes ; attendre exactement ce délai suffit, et réessayer avant ne provoque qu’un nouveau refus.

Les problèmes les plus courants

Un 4xx répété sans modification échoue à nouveau. Ces codes signalent une requête incorrecte, pas un service occupé ; seuls 429 et 5xx méritent une nouvelle tentative.
Avec 429, la réponse contient déjà Retry-After. Estimer vous-même le délai fait perdre du temps ou provoque immédiatement un nouveau refus.
402 n’est pas une panne justifiant d’alerter quelqu’un à trois heures du matin. Le quota du mois est épuisé ; surveillez X-PDFgine-Quota-Remaining et augmentez l’offre avant d’y arriver.
410 sur un téléchargement ne signifie pas un fichier perdu. La conservation est terminée : le document a été produit, comptabilisé puis supprimé selon le calendrier de votre offre.
Ne journaliser que le code de statut transforme une demande d’assistance en devinette. Journalisez aussi correlationId ; cette valeur permet de retrouver la requête.