Jede Fehlerantwort trägt denselben JSON-Envelope, der HTTP-Statuscode passt zur Semantik, und der Fehlerstring ist stabil genug, um clientseitig darauf zu schalten. Unerwartete Statuscodes melden Sie bitte an support@tracepass.eu.
Envelope
json
{
"error": "Validation error",
"details": {
"fieldErrors": {
"model": ["Required"]
}
}
}error ist immer vorhanden und ein stabiler String — schalten Sie clientseitig darauf. details ist optional; wenn vorhanden, hängt die Form vom konkreten Fehler ab (feldweise Meldungen unter fieldErrors bei Validierung, Plan- / Nutzungs-Zahlen bei Overage, Rollen- / Berechtigungs-Name bei 403).
Statuscodes
| Status | Wann | Retry? |
|---|---|---|
| 400 | Validierungsfehler — Body oder Query haben die Schema-Prüfung nicht bestanden; oder unbekannter Feldschlüssel beim Pass-PATCH. | Nein (Anfrage korrigieren) |
| 401 | Fehlender oder widerrufener API-Schlüssel, oder Sitzung abgelaufen. | Nein (neuen Schlüssel erzeugen / neu auth) |
| 402 | Tarifkontingent überschritten, wenn der Tarif einen Overage-Preis hat: `epcis_events_overage_required` beim EPCIS-Capture, `measurements_overage_required` bei Messwerten. Auf Free liefern EPCIS-Capture und Messwerte stattdessen `epcis_events_hard_block` / `measurements_hard_block`. Das Anlegen eines Passes liefert nie 402 wegen des Plan-Limits: Ein Entwurf belegt keinen Plan-Slot, das Limit greift beim Veröffentlichen im Dashboard. Wird außerdem von schreibenden v1-Aufrufen geliefert, die Inhalte anlegen oder ändern, wenn der Zahlungsstatus nicht in Ordnung ist (überfällig, unbezahlt oder gekündigt). Lesezugriffe funktionieren weiter, ebenso Prüfungen des Anwendungsbereichs, Meldungen falscher Antworten, Katalogläufe und Änderungen am Compliance-Profil. | Overage: ja, mit `confirmOverage: true`. Hard Block: nein (Upgrade). Zahlung: nein (erst Zahlung klären) |
| 403 | Workspace-Berechtigung verweigert (z. B. reine Lieferantenportal-Zugangsdaten bei einem v1-Schreibvorgang). | Nein |
| 404 | Ressource existiert nicht oder liegt in einem anderen Workspace. | Nein |
| 409 | Konflikt. Bei Pass-Schreibvorgängen: Pass ist archiviert (`passport_archived`); ein Identitätsfeld (GTIN, Seriennummer usw.) ist nach der Erstveröffentlichung gesperrt (`identifier_locked`, mit den gesperrten Feldnamen in `keys`); oder ein konkurrierender Schreibzugriff (`concurrent_update` — neu laden und erneut versuchen). Bei jedem v1-Schreibvorgang: eine Anfrage mit demselben Idempotency-Key läuft noch (`idempotency_key_in_use` — nach ihrem Abschluss mit demselben Schlüssel erneut senden). Beim Anlegen von Produkt oder Pass: doppeltes model, GTIN bei einem anderen Tenant registriert oder Seriennummern-Kollision innerhalb einer GTIN. | Bei concurrent_update und idempotency_key_in_use: ja (erneut versuchen). Andere: erst Konflikt auflösen |
| 410 | Pass abgelaufen: Das Abonnement ist beendet und die 30-tägige Karenzzeit vorbei. Er ist wieder erreichbar, sobald das Abonnement wiederhergestellt wird. Archivierte Pässe geben 404 zurück, nicht 410. | Nein |
| 413 | Payload zu groß — gilt für Multipart-Bild-Uploads (5-MB-Limit). | Nein |
| 415 | Nicht unterstützter Media-Type — Bild-Upload, der nicht PNG / JPG / WebP ist, oder eine Datei, deren Inhalt nicht zum angegebenen Typ passt. | Nein |
| 422 | Idempotency-Key mit anderem Request-Body wiederverwendet; oder bei einem Upload hat der Virenscanner Schadsoftware gefunden. | Nein (frischen Schlüssel erzeugen; bei einem Upload wird die Datei abgelehnt) |
| 423 | Ressource ist suspendiert (nur im öffentlichen Pass-Viewer). | Nein |
| 429 | Rate-Limit überschritten — Tagesschreibvorgänge oder Tages-Pass-Lesevorgänge. | Ja (nach der nächsten UTC-Mitternacht) |
| 500 | Unbehandelter Server-Fehler. Wir sind alarmiert. | Ja (mit Backoff) |
| 503 | Wartungsfenster oder Überlast (liefert Retry-After); oder bei einem Upload ist der Virenscanner kurz nicht verfügbar — nichts wird ungeprüft gespeichert. | Ja (nach Retry-After) |
Retry-Hinweise
Für die „Ja“-Zeilen oben: exponentielles Backoff mit Jitter, gedeckelt bei sechs Versuchen. Aggressive Retries verbrennen Ihr Tages-Schreib-Budget ohne Mehrwert. Der Retry-After-Header wird bei jedem 503 gesetzt; das Rate-Limit- Reset für 429 ist immer die nächste 00:00 UTC.
Häufige Fehler-Strings
| Fehler-String | Status | Bedeutung |
|---|---|---|
Validation error | 400 | Schema-Prüfung fehlgeschlagen. details.fieldErrors enthält die Begründungen, nach Feld geordnet. |
Invalid field key: <key> | 400 | PATCH .../fields/<key> hat einen Schlüssel referenziert, der nicht in der Vorlage des Passes existiert. |
No template found for category: <slug> | 400 | Die gesendete Kategorie ist nicht vorkonfiguriert — Schreibweise gegen den öffentlichen Buyer's Guide prüfen. |
A product with this model already exists for your company | 409 | model-Strings sind innerhalb eines Workspaces eindeutig. Wählen Sie ein anderes model oder aktualisieren Sie das bestehende Produkt. |
This GTIN is already registered by another company. Contact support if this is an error. | 409 | GTINs sind global tenantübergreifend eindeutig — zwei Firmen können nicht dieselbe GTIN besitzen. |
Serial number already exists for this GTIN | 409 | Wählen Sie eine andere Seriennummer. Innerhalb einer GTIN müssen Seriennummern eindeutig sein. |
passport_archived | 409 | Dieser Pass wurde archiviert. Archivierte Pässe sind dauerhaft schreibgeschützt. Ein zur Löschung markierter Pass ist ebenfalls schreibgeschützt und liefert denselben Code. |
identifier_locked | 409 | Die Anfrage würde ein Identitätsfeld (z. B. gtin, serialNumber) ändern, leeren oder seine Freigabe aufheben, obwohl es auf einem veröffentlichten Pass bereits einen freigegebenen Wert trägt. Ein Wert, der noch auf Prüfung wartet, kann korrigiert und ein leeres Feld befüllt werden. Das Array keys listet die gesperrten Felder. |
concurrent_update | 409 | Ein anderer Schreibvorgang hat den Pass geändert, während diese Änderung gespeichert wurde. Pass neu laden und erneut versuchen. |
idempotency_key_in_use | 409 | Eine Anfrage mit demselben Idempotency-Key wird noch verarbeitet. Warten Sie, bis sie abgeschlossen ist, und senden Sie dann erneut mit demselben Schlüssel: Sie erhalten ihr Ergebnis zurück. |
Idempotency-Key has already been used with a different request body. Use a new key for the new request, or reuse the original body. | 422 | Sie haben denselben Schlüssel zweimal mit verschiedenen Bodies gesendet. Erzeugen Sie einen frischen Schlüssel. |
Subscription is past due — resolve billing to continue creating new content. Published passports remain accessible. | 402 | Der Zahlungsstatus ist nicht in Ordnung. Schreibvorgänge, die Inhalte anlegen oder ändern, werden abgelehnt; alle Lesezugriffe funktionieren weiter, und veröffentlichte Pässe bleiben erreichbar. Klären Sie die Zahlung im Dashboard. |
API rate limit: N writes/day via /api/v1. Currently X today; requested Y. Retry tomorrow (UTC) or upgrade your plan. | 429 | Tägliches v1-Schreib-Budget erschöpft. Warten oder upgraden. |
API rate limit: N passports/day read via /api/v1. Currently X today; requested Y. Retry tomorrow (UTC) or contact support for a bulk export. | 429 | Tägliches v1-Pass-Lese-Budget erschöpft. Warten, upgraden, oder den JSON-LD-Bulk-Export aus dem Dashboard nutzen. |
Passport not found | 404 | Falsche ID oder falscher Workspace. Prüfen Sie, dass der API-Schlüssel zum Workspace gehört, dem der Pass gehört. |