--- title: Fehler & Rate-Limits description: "Referenz: HTTP-Statuscodes, Fehler-Envelope-Form, tägliche Aufrufkontingente auf dem kostenlosen Tier, Retry-Anleitung." canonical: "https://www.tracepass.eu/de/docs/errors" locale: de source: "https://www.tracepass.eu/de/docs/errors" --- # Fehler & Rate-Limits > Referenz: HTTP-Statuscodes, Fehler-Envelope-Form, tägliche Aufrufkontingente auf dem kostenlosen Tier, Retry-Anleitung. 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](mailto: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 (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. Der`Retry-After`\-Header wird bei jedem `503` gesetzt; das Rate-Limit- Reset für `429` ist immer die nächste 00:00 UTC. **Tip —** Paaren Sie jeden Retry mit demselben `Idempotency-Key` wie das Original — so vermeiden Sie das doppelte Anlegen eines Passes, wenn der ursprüngliche Schreibvorgang erfolgreich war, die Antwort aber verloren ging. ## 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: | 400 | PATCH .../fields/ hat einen Schlüssel referenziert, der nicht in der Vorlage des Passes existiert. | | No template found for category: | 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. | | 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. | Wir ändern den Wortlaut eines Fehler-Strings nicht in einer Minor-Version. Wenn wir einen klareren String brauchen, fügen wir ein paralleles `code`\-Feld im Envelope hinzu (numerisch, mit Namespace) und kündigen es im Regulatory Changelog an. Stabile Strings erlauben Ihnen, mit Vertrauen clientseitig zu schalten.