# 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](https://www.rfc-editor.org/rfc/rfc7807), 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. ```json { "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. ```json { "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. ```json { "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](https://dashboard.pdfblocks.com) und senden Sie die Anfrage über HTTPS. Siehe [Authentifizierung](/docs/api/authentication). ### 404: Nicht gefunden Der Pfad löst sich zu keiner Aktion auf, meist wegen eines Tippfehlers im Namen der Aktion oder eines fehlenden Versionssegments. ```json { "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](/docs/api/regions-and-data-residency) aufrufen. ### 406: Nicht erfüllbares `Accept` Eine Aktion mit mehreren Dokumenten hat einen Header `Accept` erhalten, den sie nicht erfüllen kann. ```json { "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](/docs/api/response-formats). ### 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](/docs/api/rate-limits-and-usage). **`402`: Zahlung erforderlich.** Eine Abrechnungs- oder Kontingentbedingung in Ihrem Plan. ```json { "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. ```json { "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. ```json { "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. ```json { "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](/docs/api/rate-limits-and-usage). ## 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](/docs/api/rate-limits-and-usage). Lesen Sie das Objekt `errors` immer, wenn es vorhanden ist: Es benennt genau das, was zu korrigieren ist.