Skip to content
Hilfecenter-Anleitung
2 Min. LesezeitGeprüft 2026-11-16

Fehlerbehebung & FAQs

Lösen Sie typische Publikationsblockaden, CSV-Zuordnungsfehler, Vorschauabweichungen, Push-Verzögerungen und Scanfehler.

In dieser Anleitung

Standardisiertes API-Fehlerformat

Jeder REST-Endpunkt in Passinstance API formatiert Ausnahmen über den globalen API Error Handler. Wenn ein API-Aufruf, eine Webhook-Einrichtung oder eine Scanner-Transaktion fehlschlägt, prüfen Sie die strukturierte JSON-Fehlerantwort auf die genaue Ursache und die Korrelations-requestId:

SYSTEMARCHITEKTUR-ABLAUF
INTERAKTIVE ARCHITEKTUR
FEHLERBEHANDLUNG & LOKALISIERUNG
STUFE 01 EINGEHENDE ANFRAGE (/api/v1/passes oder /api/v1/scans, Accept-Language: de-DE)
STUFE 02 DOMÄNEN- / VALIDIERUNGSAUSNAHME AUSGELÖST
Fügt strukturierten errorCode & CLIENT_SAFE_EXTENSION_KEYS hinzu
STUFE 03 GLOBALER API Error Handler & Error Catalog
Löst lokalisierte message über messageKey gemäß Accept-Language auf
Injiziert requestId, timestamp, path, retryAfter und details

Standard-Fehlerantwortschema

JSON
{
  "success": false,
  "error": "BAD_REQUEST",
  "messageKey": "api.errors.passLimitReached",
  "message": "Active wallet pass limit reached for your current subscription plan.",
  "statusCode": 400,
  "timestamp": "2026-11-16T09:20:00.000Z",
  "path": "/api/v1/passes",
  "requestId": "req_8f192b0e4c12",
  "retryAfter": 60,
  "code": "LIMIT_EXCEEDED",
  "errorCode": "PASS_LIMIT_REACHED",
  "details": [
    {
      "activePasses": 1000,
      "limit": 1000,
      "upgradeRequired": true
    }
  ]
}

Häufige errorCode-Lösungen

Verwenden Sie diese Übersicht, um typische Domänenfehlercodes in errorCode oder reasonCode in the scan response zu beheben:

errorCode / reasonCodeHTTP- / Scan-StatusUrsacheLösung
PASS_LIMIT_REACHED400 / 402Der Workspace hat das Kontingent für installedDevices im Tarif erreicht.Tarif über POST /api/v1/billing/subscription/change erweitern oder inaktive Pässe bereinigen.
PASS_VOIDED_AFTER_SCANREJECTED (ALREADY_VOIDED)Einmal-Gutschein oder Ticket (VOIDED_AFTER_SCAN scan mode) wurde bereits eingelöst.Erwarteter Betrugsschutz; vorherigen Scan-Status über GET /api/v1/scans/pass?barcode=... prüfen (Abgleich über serialNumber oder externalId).
OUT_OF_BALANCEREJECTED (FAILED)Wert- oder Prepaid-Abbuchung überschreitet das Restguthaben bei disallowNegativeBalance: true.Pass-Guthaben über /public/reload-sessions/:sessionId/initialize oder POST /api/v1/passes/:id/adjust-value aufladen.
INVALID_SCANNER_KEY401 / 403Der Header x-scanner-key fehlt, ist abgelaufen oder widerrufen.Schlüsselstatus über GET /api/v1/scanner-keys/verify prüfen oder über POST /api/v1/scanner-keys/:id/rotate rotieren.

Kurzanleitung zur Diagnose

1. Vorlage lässt sich nicht veröffentlichen

  • Vorab-Risikoprüfung ausführen: Rufen Sie GET /api/v1/templates/:id/publish-risk-check auf, um strukturierte blockers und warnings vor POST /api/v1/templates/:id/publish zu prüfen.
  • Apple-Signaturbereitschaft & bundleId prüfen: Stellen Sie sicher, dass ein gültiges, nicht abgelaufenes Apple Pass Type ID .p12-Zertifikat passend zur bundleId (passTypeIdentifier) der Vorlage im Workspace zugewiesen ist (/api/v1/certificates).
  • Farb- & Barcode-Syntax prüfen: Bestätigen Sie für Apple Wallet die Farbformatierung rgb(r, g, b) und stellen Sie sicher, dass Barcode-Nachrichtenvorlagen nur existierende Feldschlüssel ohne offene geschweifte Klammern referenzieren.

2. Live-Update erscheint nicht auf dem Smartphone

  • Geräteregistrierung prüfen: Nur Pässe im Status Aktiv in Wallets (installedDevices > 0) besitzen einen aktiven APNs- oder Google-Wallet-Pushkanal. Noch nicht installierte Karten (unclaimedPasses) können keine Push-Mitteilungen empfangen.
  • Wertänderung (changeMessage) prüfen: Apple Wallet zeigt ein Sperrbildschirm-Banner nur an, wenn sich ein Feld mit gültigem changeMessage (inklusive %@) auf einen anderen Zeichenkettenwert ändert. Das Speichern eines identischen Werts unterdrückt die Sperrbildschirm-Benachrichtigung.

3. CSV-Stapelimport lehnt Zeilen ab

  • Validieren Sie Ihre CSV-Datei über POST /api/v1/batch-processing/:id/validate, bevor Sie die Ausführung starten (POST /api/v1/batch-processing/:id/start). Prüfen Sie auf UTF-8-Kodierung, ordnen Sie Spaltenköpfe exakt den Vorlagen-Feldschlüsseln zu und entfernen Sie doppelte serialNumber- oder externalId-Zeilen.

Wichtig: Notieren Sie immer die in der JSON-Fehlerantwort zurückgegebene requestId (z. B. req_8f192b0e4c12), wenn Sie einen Vorfall über Support kontaktieren eskalieren.

Weitere Antworten zur Plattform finden Sie in der Support-Übersicht.

Weiterführende Produkt- & Entwicklerdoku

Bereit für Ihr erstes Wallet-Kartenprogramm?

Erstellen Sie Ihren Workspace, konfigurieren Sie Ihre Vorlage und testen Sie eine echte Karte in Apple Wallet und Google Wallet, bevor Sie skalieren.