Produkt- und API-Leitfaden

Fehler

Fehler werden als RFC-9457-problem+json zurückgegeben. Jede Antwort enthält correlationId. Geben Sie sie beim Kontakt mit dem Support an.

Status	Bedeutung	Empfohlene Aktion
`401`	Schlüssel fehlt oder ist ungültig	Prüfen Sie den Header X-PDFgine-Key und ob der Schlüssel widerrufen wurde.
`402`	Kontingent aufgebraucht	Wechseln Sie zu einem höheren Tarif oder warten Sie auf den neuen Abrechnungszeitraum.
`404`	Vorlage oder Dokument nicht gefunden	Prüfen Sie den Vorlagencode und ob eine veröffentlichte Revision vorhanden ist.
`429`	Ratenlimit überschritten	Warten Sie die im Header Retry-After angegebene Anzahl Sekunden und versuchen Sie es erneut.

Ratenlimits richten sich nach dem Tarif

Die Minuten- und Stundenlimits der Erstellungsendpunkte gelten pro MANDANT und ergeben sich aus Ihrem Tarif; die folgende Tabelle zeigt sie. Da pro Mandant statt pro Schlüssel gezählt wird, erhöht ein zweiter API-Schlüssel das Limit nicht. Eine 429-Antwort nennt das erreichte Zeitfenster im Header X-PDFgine-RateLimit-Scope: tenant-api, tenant-render-minute oder tenant-render-hour. Senden Sie bei Stapelverarbeitung bis zu 100 Dokumente in einer /document-batches-Anfrage statt eines Dokuments pro Anfrage.

Antwort bei aufgebrauchtem Kontingent

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

{
  "title": "Seitenkontingent überschritten",
  "status": 402,
  "detail": "Ihr Tarif hat das verfügbare Seitenkontingent aufgebraucht.",
  "correlationId": "114249cb1dbc52a29026ab2eca5c4b72"
}

Retry-After und das Zeitfenster

Zwei Obergrenzen greifen nacheinander. Die erste schützt den Dienst und zählt pro Zugangsdaten: 30 Anfragen je Zeitfenster ohne Schlüssel, 120 mit Schlüssel, bei einer Fensterdauer von 60 Sekunden. Die zweite ergibt sich aus Ihrem Tarif und zählt pro Mandant.

Tarif	Dokumente / Minute	Dokumente / Stunde
Kostenlos	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"
}

Das Zeitfenster ist fest statt gleitend: Es beginnt mit der ersten Anfrage, alle Anfragen darin zählen zum selben Kontingent; danach wird der Zähler zurückgesetzt. Retry-After nennt die verbleibenden Sekunden. Genau so lange zu warten reicht aus; frühere Versuche führen nur zu einer weiteren Ablehnung.

Häufige Fehler

Eine unveränderte Anfrage mit 4xx scheitert erneut. Diese Codes weisen auf einen falschen Request hin, nicht auf Dienstauslastung. Nur 429 und 5xx sind Wiederholungen wert.
Bei 429 enthält die Antwort bereits Retry-After. Eine selbst geschätzte Wartezeit verschwendet entweder Zeit oder führt direkt zur nächsten Ablehnung.
402 ist kein Störfall, für den Sie jemanden nachts um drei alarmieren müssen. Das Monatskontingent ist aufgebraucht. Beobachten Sie X-PDFgine-Quota-Remaining und erhöhen Sie den Tarif rechtzeitig.
410 beim Download bedeutet nicht, dass eine Datei verloren ging. Die Aufbewahrungszeit ist abgelaufen: Das Dokument wurde erstellt, gezählt und nach dem Zeitplan Ihres Tarifs entfernt.
Nur den Statuscode zu protokollieren macht Supportanfragen zum Ratespiel. Protokollieren Sie auch correlationId; dieser Wert findet die Anfrage.