Jede Fehlerantwort trägt denselben JSON-Envelope, der HTTP-Statuscode passt zur Semantik, und der Fehlerstring ist stabil genug, um clientseitig darauf zu schalten. Die Liste unten ist vollständig — wenn Sie auf etwas stoßen, das nicht dabei ist, melden Sie es bitte an support@tracepass.eu.
Envelope
{
"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 (geflattetes Zod-Ergebnis 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 | DPP-Kontingent beim Pass-Create-Aufruf erschöpft. Mit `confirmOverage: true` erneut versuchen, falls der Plan Overage unterstützt. Wird auch ausgelöst, wenn ein aktives Abo verlangt ist, das aber past_due/canceled ist. | Ja, mit `confirmOverage: true` |
| 403 | Plan-Gate (z. B. v1-API auf einem Free-Plan) oder Workspace-Berechtigung verweigert. | Nein |
| 404 | Ressource existiert nicht oder liegt in einem anderen Workspace. | Nein |
| 409 | Konflikt — doppeltes model auf einem Produkt, GTIN bei einem anderen Tenant registriert, Seriennummern-Kollision innerhalb einer GTIN. | Manchmal (Konflikt auflösen, dann erneut versuchen) |
| 410 | Ressource dauerhaft entfernt (selten; betrifft hauptsächlich öffentliche Pass-URLs nach Archivierung). | 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. | Nein |
| 422 | Idempotency-Key mit anderem Request-Body wiederverwendet. | Nein (frischen Schlüssel erzeugen) |
| 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. | Ja (nach Retry-After) |
Retry-Hinweise
Für die „Ja“-Zeilen oben: exponentielles Backoff mit Jitter, gedeckelt bei sechs Versuchen. Wir akzeptieren keine Retries aggressiver als einmal pro Sekunde auf einem einzelnen Endpoint — schneller erreicht die Datenbank ohnehin nichts (der In-Memory-Rate-Limiter weist ab), aber Sie verbrennen Ihr Tages-Schreib-Budget. DerRetry-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 trägt die feldweise Begründung (Zod flatten()). |
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 gesäht — 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. |
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. |
overage_required | 402 | DPP-Kontingent erschöpft. Body trägt planLimit + currentUsage + extraPriceCents. Mit `confirmOverage: true` erneut versuchen, um die Pro-Pass-Gebühr zu akzeptieren. |
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. |