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

Bekannte Einschränkungen & Limits

Transparente Plattformgrenzen von Apple, Google, Samsung Wallet, Mailanbietern und Offline-Scanner-Caching.

In dieser Anleitung

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.

SYSTEMARCHITEKTUR-ABLAUF
INTERAKTIVE ARCHITEKTUR
INGRESS-RATE-LIMITING & IDEMPOTENZSPERREN
STUFE 01 CLIENT- / POS- / INTEGRATIONSANFRAGE
Maximale JSON-/Multipart-Body-Größe: 10MB (BODY_LIMIT)
STUFE 02 GLOBALER 1-SEKUNDEN-BURST-RATE-LIMITER (main.ts)
Sendet RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset
Bei ÜberschreitungGibt HTTP 429 Too Many Requests (Retry-After: 1) aus
STUFE 03 IDEMPOTENZSCHUTZ (Idempotency Engine)
Sperrt gleichzeitige doppelte x-idempotency-key-Anfragen
Erzwingt DB-Constraints: ux_scan_config_idempotency & ux_pos_tx_tenant_idempotency

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-HeaderBeschreibung
RateLimit-Limit / X-RateLimit-LimitMaximal zulässige Anfragen innerhalb des aktuellen 1-Sekunden-Burst-Zeitfensters.
RateLimit-Remaining / X-RateLimit-RemainingVerbleibende zulässige Anfragen im aktiven Zeitfenster vor einer Drosselung.
RateLimit-Reset / X-RateLimit-ResetVerbleibende Sekunden bis zum Zurücksetzen des Rate-Limit-Kontingents.
Retry-AfterSekunden, die nach Erhalt einer HTTP 429-Antwort vor einem erneuten Versuch abgewartet werden müssen.

Payload einer gedrosselten HTTP-429-Antwort:

JSON
{
  "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 von 10MB (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 (oder idempotencyKey in POST /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, serialNumber oder externalId abgeglichen werden.

Plattformseitige Wallet-Einschränkungen (Apple & Google)

Mehrere Verhaltensgrenzen ergeben sich direkt aus den Betriebssystemarchitekturen von Apple iOS und Google Android:

EinschränkungPlattformTechnische 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 KlassenbilderGoogle Wallet vs. Apple WalletApple 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 WertApple WalletiOS 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 WatchApple Wallet + watchOSEine 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 NetzwerkeiOS Instagram, TikTok, LinkedInEingebettete 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-HardwareVerschlü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.

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.