API-Gateway-, Payload- & Nebenläufigkeitslimits
Um eine Kartengenerierung mit niedriger Latenz zu gewährleisten und die Stabilität in einer mandantenfähigen Umgebung zu schützen, setzt Passinstance API deterministische Rate-Limits, Obergrenzen für die Payload-Größe und Idempotenzsperren am Ingress-Gateway durch.
Rate-Limit-Header & Umgang mit HTTP 429
Jede API-Antwort enthält standardmäßige RFC- sowie Legacy-Rate-Limiting-Header, sodass Integrations-Clients Massenoperationen automatisch drosseln können:
| Antwort-Header | Beschreibung |
|---|---|
RateLimit-Limit / X-RateLimit-Limit | Maximal zulässige Anfragen innerhalb des aktuellen 1-Sekunden-Burst-Zeitfensters. |
RateLimit-Remaining / X-RateLimit-Remaining | Verbleibende zulässige Anfragen im aktiven Zeitfenster vor einer Drosselung. |
RateLimit-Reset / X-RateLimit-Reset | Verbleibende Sekunden bis zum Zurücksetzen des Rate-Limit-Kontingents. |
Retry-After | Sekunden, die nach Erhalt einer HTTP 429-Antwort vor einem erneuten Versuch abgewartet werden müssen. |
Payload einer gedrosselten HTTP-429-Antwort:
{
"error": "Rate limit exceeded",
"retryAfter": 1
}
Einschränkungen bei Anfrage-Payloads & Idempotenz
-
Maximale Größe des Request-Bodys (
10MB): Das API-Gateway setzt über alle JSON-Anfragen und Datei-Uploads hinweg ein striktes Payload-Limit von10MB(BODY_LIMIT) durch. Verwenden Sie für die Ausstellung großer Kartenvolumina von mehr als einigen Hundert Datensätzen den asynchronen CSV-Batch-Worker (POST /api/v1/batch-processing) oder aufgeteilte Array-Operationen (POST /api/v1/batch-pass-operations/create) anstelle einzelner übergroßer Anfragen. -
Idempotenzsperren: Gleichzeitige Scanner- oder POS-Einlösungsaufrufe mit demselben
x-idempotency-key(oderidempotencyKeyinPOST /v1/pos/redeem) werden über in-memory cache-Sperren und eindeutige Datenbankindizes (ux_scan_config_idempotency,ux_pos_tx_tenant_idempotency) serialisiert, um Doppelabbuchungen in instabilen Veranstaltungsnetzwerken zu verhindern, wobei Karten anhand von Barcode,serialNumberoderexternalIdabgeglichen werden.
Plattformseitige Wallet-Einschränkungen (Apple & Google)
Mehrere Verhaltensgrenzen ergeben sich direkt aus den Betriebssystemarchitekturen von Apple iOS und Google Android:
| Einschränkung | Plattform | Technische Ursache & empfohlene Lösung |
|---|---|---|
APNs-Silent-Push-Limit (4096 bytes) | Apple Wallet (APNs) | Der Apple Push Notification service beschränkt Payloads auf 4096 bytes. Passinstance sendet einen leichtgewichtigen leeren Push {}, um das iPhone aufzuwecken, das anschließend das vollständige .pkpass-Paket (signiert mit der bundleId / dem passTypeIdentifier der Vorlage) über GET /v1/passes/:passTypeIdentifier/:serialNumber abruft. |
| Caching gemeinsam genutzter Klassenbilder | Google Wallet vs. Apple Wallet | Apple lädt bei einem Update das gesamte .pkpass-ZIP-Archiv neu herunter und aktualisiert Strip-/Thumbnail-Bilder sofort. Google Wallet speichert gemeinsam genutzte Hero-/Logo-URLs auf Class-Ebene auf Android-Geräten aggressiv im Cache; hängen Sie einen Cache-Busting-Dateinamen an oder aktualisieren Sie Felder auf Object-Ebene für sofortige visuelle Änderungen. |
| Unterdrückung von Push-Bannern bei identischem Wert | Apple Wallet | iOS zeigt ein Benachrichtigungsbanner auf dem Sperrbildschirm nur dann an, wenn sich ein Feld mit einer changeMessage auf einen neuen Zeichenfolgenwert ändert. Das erneute Speichern exakt desselben Werts erzeugt kein Banner. |
| Registrierung einer gekoppelten Apple Watch | Apple Wallet + watchOS | Eine einzelne Karte, die auf einem iPhone installiert ist und mit einer gekoppelten Apple Watch synchronisiert wird, registriert 2 separate Geräte-Push-Tokens (installedDevices = 2) für 1 Karteninstanz. |
| Blockierung in In-App-Browsern sozialer Netzwerke | iOS Instagram, TikTok, LinkedIn | Eingebettete WebViews von Social-Media-Apps blockieren häufig application/vnd.apple.pkpass-MIME-Streams. Intelligente Download-Seiten (/d/:slug) erkennen WebViews und leiten Karteninhaber an, den Link im nativen Safari-Browser zu öffnen. |
Verschlüsseltes NFC (NFC_VAS / NFC_SMART_TAP) | iOS- & Android-NFC-Hardware | Verschlüsseltes kontaktloses Einlösen (Tap-to-Redeem) erfordert zertifizierte Lesegeräte-Hardware sowie explizite Händlerberechtigungen (Entitlements) für Apple VAS oder Google Smart Tap – es ist standardmäßig niemals aktiviert. |
Wichtig: Bei der Durchführung von Massen-Updates für Zehntausende aktive Karten steuern die background job queue-Hintergrund-Worker von Passinstance ausgehende Apple-APNs-HTTP/2-Streams und Google-Wallet-REST-PATCH-Aufrufe automatisch so, dass die Kontingente der vorgelagerten Cloud-Anbieter eingehalten werden.
Hinweise zur Entwicklerintegration finden Sie unter API-Übersicht & Authentifizierung sowie Plattformunterschiede & Einschränkungen.
