Fehler — PassportCraft API

Fehler

Jeder Fehlschlag trägt einen stabilen Code. Verzweigen Sie auf den Code und niemals auf die Meldung: der Wortlaut kann sich jederzeit ändern, der Code nicht.

Pfade, Methoden, Scopes, Feldnamen und Fehlercodes erscheinen auf Englisch, denn Englisch ist die Sprache der Schnittstelle selbst — es ist das, was ein Aufrufer eintippt oder abgleicht. Ebenso jedes Codebeispiel, jede JSON-Nutzlast und der exakte Satz, den eine Fehlerantwort mitführt: /v1 wertet Accept-Language nicht aus, und eine Übersetzung dessen, was die API tatsächlich sendet, würde sie falsch beschreiben. Alles, was darüber geschrieben steht, folgt der Sprache dieser Seite.

Die Fehlerhülle

Jede Antwort außerhalb von 2xx hat dieselbe Form. documentation_url zeigt direkt auf den passenden Eintrag weiter unten, und request_id ist der Wert, den man in einer Supportanfrage nennt. details trägt maschinenlesbaren Kontext — bei einem abgelehnten Körper sind das die issues, jede davon ein JSON Pointer auf das beanstandete Feld.

Antwort

{
  "error": {
    "code": "validation_failed",
    "message": "The request body failed validation.",
    "documentation_url": "https://passportcraft.com/docs/api/errors#validation_failed",
    "request_id": "req_9Fv2KpQ0aXbT4Lmn",
    "details": {
      "issues": [
        { "source": { "pointer": "/data/product_name" }, "rule": "required" }
      ]
    }
  }
}

Codes

Jeder Code ist aus der Antwort verlinkt, die ihn trägt; diese Seite wird also meist direkt beim benötigten Eintrag betreten.

invalid_key

401

Der übergebene Zugangsschlüssel ist ungültig.

API sendetThe API key provided is not valid.

Jeder Endpunkt kann das zurückgeben.

key_revoked

401

Dieser Zugangsschlüssel wurde widerrufen.

API sendetThis API key has been revoked.

Jeder Endpunkt kann das zurückgeben.

key_expired

401

Dieser Zugangsschlüssel ist abgelaufen.

API sendetThis API key has expired.

Jeder Endpunkt kann das zurückgeben.

key_rotated

401

Dieser Zugangsschlüssel wurde im Zuge einer Rotation ersetzt, und sein Überlappungsfenster ist inzwischen geschlossen.

API sendetThis API key was replaced by a rotation and its overlap window has closed.

Jeder Endpunkt kann das zurückgeben.

mode_mismatch

400

Das Präfix des Schlüssels passt nicht zu den Zugangsdaten. Prüfen Sie, ob Sie einen Test- oder einen Live-Schlüssel meinten.

API sendetThe key prefix does not match the credential. Check whether you meant a test or a live key.

Jeder Endpunkt kann das zurückgeben.

insufficient_scope

403

Diese Zugangsdaten tragen nicht den Scope, den diese Operation verlangt.

API sendetThis credential does not carry the scope required for this operation.

Welche Endpunkte das zurückgeben

organization_not_found_or_not_granted

404

Eine solche Organisation gibt es nicht.

API sendetNo such organization.

Welche Endpunkte das zurückgeben

resource_not_found

404

Eine solche Ressource gibt es nicht.

API sendetNo such resource.

Welche Endpunkte das zurückgeben

wildcard_not_supported

400

Die Organisations-Wildcard „-“ ist reserviert und wird noch nicht unterstützt.

API sendetThe "-" organization wildcard is reserved and not yet supported.

Welche Endpunkte das zurückgeben

validation_failed

422

Der Anfragekörper hat die Validierung nicht bestanden.

API sendetThe request body failed validation.

Welche Endpunkte das zurückgeben

invalid_request

400

Die Anfrage konnte nicht verstanden werden.

API sendetThe request could not be understood.

Jeder Endpunkt kann das zurückgeben.

method_not_allowed

405

Den Endpunkt gibt es, aber er beantwortet diese HTTP-Methode nicht. Der Allow-Header der Ablehnung nennt die Methoden, die er beantwortet.

API sendetThis endpoint does not support that HTTP method. The Allow header lists the ones it does.

payload_too_large

413

Der Anfragekörper ist größer, als dieser Endpunkt annimmt. details.limit_bytes nennt die angewandte Obergrenze.

API sendetThe request body is larger than this endpoint accepts.

Jeder Endpunkt kann das zurückgeben.

unsupported_media_type

415

Der Anfragekörper kam nicht als application/json an.

API sendetThe request body must be sent as application/json.

Welche Endpunkte das zurückgeben

idempotency_conflict

409

Dieser Idempotency-Key wurde bereits mit einem anderen Anfragekörper verwendet.

API sendetThis Idempotency-Key was already used with a different request body.

Welche Endpunkte das zurückgeben

precondition_failed

412

Die Ressource hat sich seit der von Ihnen angegebenen Version geändert.

API sendetThe resource changed since the version you supplied.

Welche Endpunkte das zurückgeben

resource_busy

409

Eine andere Anfrage bearbeitet diese Ressource gerade. Warten Sie die im Retry-After-Header angegebene Zeit ab und versuchen Sie es dann erneut.

API sendetAnother request is modifying this resource. Wait for the Retry-After header, then retry.

Welche Endpunkte das zurückgeben

delete/organizations/{organization}/passports/{id}/documents/{documentId}

cursor_invalid

400

Der Cursor zum Blättern ist ungültig, abgelaufen oder wurde mit anderen Filtern gesendet.

API sendetThe pagination cursor is invalid, expired, or was sent with different filters.

Welche Endpunkte das zurückgeben

no_subscription

402

Diese Organisation hat kein aktives Abonnement.

API sendetThis organization has no active subscription.

Welche Endpunkte das zurückgeben

payment_overdue

402

Das Veröffentlichen ist gesperrt, solange eine Zahlung offen ist.

API sendetPublishing is disabled while payment is overdue.

Welche Endpunkte das zurückgeben

gtin_required

422

Vor der Veröffentlichung dieses Produktpasses ist eine GTIN erforderlich.

API sendetA GTIN is required before this passport can be published.

Welche Endpunkte das zurückgeben

wrong_status

409

Der Produktpass ist nicht in einem Status, der diese Operation zulässt.

API sendetThe passport is not in a status that allows this operation.

Welche Endpunkte das zurückgeben

not_trashed

409

Nur ein Produktpass im Papierkorb lässt sich wiederherstellen.

API sendetOnly a trashed passport can be restored.

Welche Endpunkte das zurückgeben

post/organizations/{organization}/passports/{id}/restore

publish_limit_reached

402

Diese Organisation hat alle Veröffentlichungsplätze belegt, die ihr Tarif zulässt.

API sendetThis organization has used every publish slot its plan allows.

Welche Endpunkte das zurückgeben

post/organizations/{organization}/passports/{id}/publish

unit_limit_reached

402

Dieser Produktpass trägt mehr Einheiten, als der Tarif zulässt.

API sendetThis passport carries more units than the plan allows.

Welche Endpunkte das zurückgeben

document_missing

422

Ein Pflichtfeld wird allein durch ein Dokument erfüllt, das nicht mehr angehängt ist.

API sendetA required field is satisfied only by a document that is no longer attached.

Welche Endpunkte das zurückgeben

post/organizations/{organization}/passports/{id}/publish

delegation_required

403

Die Hinterlegung setzt eine aktive Delegation voraus, die zum Zeitpunkt des Aufrufs gegen das Portal geprüft wird.

API sendetFiling requires an active delegation, verified against the portal at call time.

Welche Endpunkte das zurückgeben

post/organizations/{organization}/passports/{id}/affichage

attestation_required

403

Diese Operation setzt eine Bestätigung voraus, die eine namentlich benannte Person der Marke angenommen hat.

API sendetThis operation requires an attestation accepted by a named person at the brand.

Welche Endpunkte das zurückgeben

post/organizations/{organization}/passports/{id}/affichage

test_mode_refused

403

Mit Zugangsdaten im Testmodus lässt sich diese Operation nicht ausführen.

API sendetTest-mode credentials cannot perform this operation.

Welche Endpunkte das zurückgeben

post/organizations/{organization}/passports/{id}/affichage

portal_unavailable

502

Das französische Portal affichage-environnemental war nicht erreichbar, es wurde daher nichts hinterlegt.

API sendetThe French affichage portal could not be reached, so nothing was filed.

Welche Endpunkte das zurückgeben

post/organizations/{organization}/passports/{id}/affichage

storage_unavailable

503

Wir konnten nicht bestätigen, ob die hochgeladenen Dateien im Speicher liegen, daher wurde nichts veröffentlicht. An Ihrer Anfrage ist nichts falsch — versuchen Sie es nach der im Retry-After-Header angegebenen Wartezeit erneut.

API sendetWe could not confirm whether the uploaded files are in storage, so nothing was published. Nothing is wrong with your request — retry after the delay in the Retry-After header.

Welche Endpunkte das zurückgeben

entitlement_unavailable

503

Wir konnten die Berechtigung dieser Organisation nicht bestätigen, daher wurde nichts eingereicht. Das ist keine Aussage über den Tarif — versuchen Sie es nach der im Retry-After-Header angegebenen Wartezeit erneut.

API sendetWe could not confirm this organization’s entitlement, so nothing was filed. This is not a statement about the plan — retry after the delay in the Retry-After header.

Welche Endpunkte das zurückgeben

post/organizations/{organization}/passports/{id}/affichage

rate_limited

429

Zu viele Anfragen.

API sendetToo many requests.

Jeder Endpunkt kann das zurückgeben.

internal_error

500

Auf unserer Seite ist etwas schiefgegangen.

API sendetSomething went wrong on our side.

Jeder Endpunkt kann das zurückgeben.

configuration_error

500

Der Dienst ist fehlerhaft konfiguriert. Das liegt nicht an Ihrer Anfrage.

API sendetThe service is misconfigured. This is not a problem with your request.

Jeder Endpunkt kann das zurückgeben.

Warnungen

Eine Warnung ist keine Ablehnung. Sie kommt neben einer 200 an, bei einem gelungenen Aufruf, und benennt etwas, das Beachtung verdient.

environmental_claim_detected

200

Der Produktpass enthält Formulierungen mit Umweltbezug. Die Veröffentlichung war erfolgreich und der Produktpass ist live. Ab dem 27. September 2026 verlangt die Richtlinie (EU) 2024/825, dass der Händler, der das Produkt in Verkehr bringt, solche Aussagen belegen kann.