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:
Standard-Fehlerantwortschema
{
"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 / reasonCode | HTTP- / Scan-Status | Ursache | Lösung |
|---|---|---|---|
PASS_LIMIT_REACHED | 400 / 402 | Der 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_SCAN | REJECTED (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_BALANCE | REJECTED (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_KEY | 401 / 403 | Der 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-checkauf, um strukturierteblockersundwarningsvorPOST /api/v1/templates/:id/publishzu prüfen. -
Apple-Signaturbereitschaft &
bundleIdprüfen: Stellen Sie sicher, dass ein gültiges, nicht abgelaufenes Apple Pass Type ID.p12-Zertifikat passend zurbundleId(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ültigemchangeMessage(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 doppelteserialNumber- oderexternalId-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.
