PDF Blocks
PreiseSupport
Kostenlos starten
Seite öffnen

Fehler

Das Fehlerformat problem+json, die Bedeutung jedes Statuscodes und der Umgang mit einer fehlgeschlagenen Anfrage im Code.

Wenn eine Anfrage fehlschlägt, gibt PDF Blocks einen HTTP-Standardstatuscode und einen maschinenlesbaren Antworttext zurück, der beschreibt, was schiefgelaufen ist. Fehler folgen den Problemdetails aus RFC 7807, sodass Sie jeden Fehlschlag auf dieselbe Weise auswerten, unabhängig davon, welche Aktion ihn erzeugt hat.

Das Modell problem+json

Fehlerantworten haben Content-Type: application/problem+json und diese Form:

Attribut Typ Beschreibung
type string Eine URL zur Dokumentation des Problems.
title string Eine menschenlesbare Zusammenfassung des Problems.
status integer Der HTTP-Statuscode, im Antworttext gespiegelt.
errors object Feldnamen, zugeordnet zu Arrays von Fehlermeldungen.

Die URL type endet immer auf den Statuscode, zum Beispiel https://www.pdfblocks.com/docs/api/v1/error/400, sodass Sie darauf oder auf status verzweigen können. Das Objekt errors ist vorhanden, wenn ein Fehlschlag an bestimmte Felder der Anfrage gebunden ist (Validierung); bei Fehlschlägen auf Ebene der Anfrage, etwa einem falschen API-Schlüssel, kann es fehlen.

{
  "type": "https://www.pdfblocks.com/docs/api/v1/error/400",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "file": [
      "Could not parse the PDF document. The file may be invalid or corrupt."
    ]
  }
}

Statuscodes

Status Bedeutung Was zu tun ist
400 Validierungsfehler Die genannten Felder korrigieren und erneut senden.
401 Nicht autorisiert Einen gültigen X-API-Key senden.
404 Nicht gefunden Route der Aktion und Host prüfen.
406 Nicht erfüllbares Accept Ein unterstütztes Format anfordern.
402 Zahlung erforderlich (reserviert) Abrechnung oder Kontingent klären.
403 Verboten (reserviert) Der Schlüssel ist für diesen Aufruf nicht zugelassen.
413 Nutzlast zu groß (reserviert) Eine kleinere Datei senden.
429 Zu viele Anfragen (reserviert) Die Rate drosseln und erneut versuchen.
5xx Serverfehler (selten) Mit Backoff erneut versuchen.

400: Validierungsfehler

Ein Parameter ist ungültig, oder file ist kein lesbares PDF. Das Objekt errors benennt jedes beanstandete Feld.

{
  "type": "https://www.pdfblocks.com/docs/api/v1/error/400",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "line_1": ["The field line_1 must be a string with a maximum length of 32."]
  }
}

Lesen Sie errors Feld für Feld, korrigieren Sie die Eingabe und senden Sie erneut. Ein 400 wird ohne Änderungen auch bei einem erneuten Versuch nicht erfolgreich sein.

401: Nicht autorisiert

Der Header X-API-Key fehlt, ist fehlerhaft aufgebaut oder enthält keinen gültigen Schlüssel.

{
  "type": "https://www.pdfblocks.com/docs/api/v1/error/401",
  "title": "The request is missing a valid API key.",
  "status": 401
}

Setzen Sie den Header X-API-Key auf einen gültigen Schlüssel aus Ihrem Dashboard und senden Sie die Anfrage über HTTPS. Siehe Authentifizierung.

404: Nicht gefunden

Der Pfad löst sich zu keiner Aktion auf, meist wegen eines Tippfehlers im Namen der Aktion oder eines fehlenden Versionssegments.

{
  "type": "https://www.pdfblocks.com/docs/api/v1/error/404",
  "title": "The requested resource was not found.",
  "status": 404
}

Prüfen Sie die Route, zum Beispiel /v1/add_text_watermark, und ob Sie eine gültige Basis-URL aufrufen.

406: Nicht erfüllbares Accept

Eine Aktion mit mehreren Dokumenten hat einen Header Accept erhalten, den sie nicht erfüllen kann.

{
  "type": "https://www.pdfblocks.com/docs/api/v1/error/406",
  "title": "The requested Accept header cannot be satisfied.",
  "status": 406
}

Fordern Sie eines der unterstützten Formate an (application/zip, application/json oder multipart/mixed) oder lassen Sie Accept weg, um die ZIP-Voreinstellung zu erhalten. Siehe Antwortformate.

Reservierte Statuscodes

Vorausschauend. Die Antworten 402, 403, 413 und 429 sind Teil des Vertrags der API, werden aber noch nicht durchgesetzt. Behandeln Sie sie schon jetzt, damit Ihr Client bereit ist, wenn sie in Betrieb gehen. Einzelheiten zu Nutzung und Rate-Limiting finden Sie unter Rate-Limits und Nutzung.

402: Zahlung erforderlich. Eine Abrechnungs- oder Kontingentbedingung in Ihrem Plan.

{
  "type": "https://www.pdfblocks.com/docs/api/v1/error/402",
  "title": "Payment is required to complete this request.",
  "status": 402
}

403: Verboten. Der Schlüssel ist gültig, darf diese Ressource aber nicht verwenden.

{
  "type": "https://www.pdfblocks.com/docs/api/v1/error/403",
  "title": "You do not have permission to access this resource.",
  "status": 403
}

413: Nutzlast zu groß. Der Anfragetext überschreitet die zulässige Größe.

{
  "type": "https://www.pdfblocks.com/docs/api/v1/error/413",
  "title": "The request payload is too large.",
  "status": 413
}

429: Zu viele Anfragen. Sie haben das Rate-Limit Ihres Plans überschritten.

{
  "type": "https://www.pdfblocks.com/docs/api/v1/error/429",
  "title": "Too many requests. Please retry later.",
  "status": 429
}

5xx: Serverfehler

Ein Status 5xx weist auf ein Problem auf unserer Seite hin und ist selten. Er ist vorübergehend: Wiederholen Sie dieselbe Anfrage mit exponentiellem Backoff.

Fehler im Code behandeln

Werten Sie den Antworttext einmal aus und verzweigen Sie auf status oder auf den Statuscode am Ende von type:

  • 400: Lesen Sie das Objekt errors, ordnen Sie jede Meldung ihrem Feld zu und korrigieren Sie die Eingabe. Wiederholen Sie die Anfrage nicht blind, denn dieselbe Anfrage schlägt erneut fehl.
  • 401, 403, 404, 406: Die Anfrage selbst ist falsch. Korrigieren Sie den Header, die Route oder Accept und senden Sie erneut; ein unveränderter erneuter Versuch hilft nicht.
  • 402, 413: Eine Bedingung beim Konto oder bei der Größe. Klären Sie die Abrechnung oder senden Sie eine kleinere Datei; unverändert werden diese Anfragen bei einem erneuten Versuch nicht erfolgreich sein.
  • 429 und 5xx: Vorübergehend. Wiederholen Sie die Anfrage mit exponentiellem Backoff, beachten Sie einen vorhandenen Header Retry-After und begrenzen Sie die Zahl Ihrer Versuche. Siehe Rate-Limits und Nutzung.

Lesen Sie das Objekt errors immer, wenn es vorhanden ist: Es benennt genau das, was zu korrigieren ist.