Skip to content
Help Center Guide
3 min readVerified 2026-11-16

Known Issues & Limitations

Transparent platform constraints from Apple, Google, Samsung Wallet, email providers, and offline scanner caching.

In This Guide

API Gateway, Payload & Concurrency Limits

To maintain low-latency pass generation and protect multi-tenant stability, Passinstance API enforces deterministic rate limits, payload size ceilings, and idempotency locks at the ingress boundary.

SYSTEM ARCHITECTURE FLOW
INTERACTIVE ARCHITECTURE
INGRESS RATE LIMITING & IDEMPOTENCY LOCKS
STAGE 01 CLIENT / POS / INTEGRATION REQUEST
Max JSON/Multipart Body Size: 10MB (BODY_LIMIT)
STAGE 02 GLOBAL 1-SECOND BURST RATE LIMITER (main.ts)
Emits RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset
If exceededReturns HTTP 429 Too Many Requests (Retry-After: 1)
STAGE 03 IDEMPOTENCY PROTECTION GUARD
Locks concurrent duplicate x-idempotency-key requests
Enforces DB constraints: ux_scan_config_idempotency & ux_pos_tx_tenant_idempotency

Rate Limit Headers & HTTP 429 Handling

Every API response includes standard RFC and legacy rate-limiting headers so integration clients can pace bulk operations automatically:

Response HeaderDescription
RateLimit-Limit / X-RateLimit-LimitMaximum requests allowed within the current 1-second burst window.
RateLimit-Remaining / X-RateLimit-RemainingRemaining requests permitted in the active window before throttling.
RateLimit-Reset / X-RateLimit-ResetSeconds remaining until the rate-limit bucket resets.
Retry-AfterSeconds to wait before retrying after receiving an HTTP 429 response.

HTTP 429 Throttled Response Payload:

JSON
{
  "error": "Rate limit exceeded",
  "retryAfter": 1
}

Request Payload & Idempotency Constraints

  • Maximum Request Body (10MB): The API gateway enforces a strict 10MB payload limit (BODY_LIMIT) across JSON requests and file uploads. For high-volume pass issuance exceeding a few hundred records, use the asynchronous CSV batch worker (POST /api/v1/batch-processing) or chunked array operations (POST /api/v1/batch-pass-operations/create) rather than single oversized requests.
  • Idempotency Locking: Concurrent scanner or POS redemption calls sharing the same x-idempotency-key (or idempotencyKey in POST /v1/pos/redeem) are serialized via in-memory cache locks and database unique indices (ux_scan_config_idempotency, ux_pos_tx_tenant_idempotency) to prevent double-deduction on flaky venue networks, matching passes by barcode, serialNumber, or externalId.

Platform-Level Wallet Constraints (Apple & Google)

Several behavioral boundaries originate directly from Apple iOS and Google Android operating system architectures:

ConstraintPlatformTechnical Reality & Recommended Workaround
APNs Silent Push Limit (4096 bytes)Apple Wallet (APNs)Apple Push Notification service restricts payloads to 4096 bytes. Passinstance sends a lightweight empty push {} to wake the iPhone, which then pulls the full .pkpass bundle (signed by the template's bundleId / passTypeIdentifier) via GET /v1/passes/:passTypeIdentifier/:serialNumber.
Shared Class Imagery CachingGoogle Wallet vs. Apple WalletApple re-downloads the complete .pkpass ZIP archive on update, refreshing strip/thumbnail images immediately. Google Wallet caches shared Class-level hero/logo URLs aggressively on Android devices; append a cache-busting filename or update Object-level fields for instant visual changes.
Identical-Value Push SuppressionApple WalletiOS displays a lock-screen notification banner only when a field with a changeMessage mutates to a new string value. Re-saving the exact same value produces no banner.
Paired Apple Watch RegistrationApple Wallet + watchOSA single pass installed on an iPhone synced with a paired Apple Watch registers 2 distinct device push tokens (installedDevices = 2) across 1 pass instance.
In-App Social WebView BlockingiOS Instagram, TikTok, LinkedInEmbedded social-app webviews often block application/vnd.apple.pkpass MIME streams. Smart download pages (/d/:slug) detect webviews and guide passholders to open the link in native Safari.
Encrypted NFC (NFC_VAS / NFC_SMART_TAP)iOS & Android NFC HardwareEncrypted tap-to-redeem requires certified reader hardware (e.g., certified NFC) plus explicit Apple VAS or Google Smart Tap merchant entitlements — it is never enabled by default.

Important: When executing bulk pass updates across tens of thousands of active cards, Passinstance's background job queue background workers automatically pace outbound Apple APNs HTTP/2 streams and Google Wallet REST PATCH calls to respect upstream cloud provider quotas.

For developer integration guidance, review API Overview & Authentication and Platform Differences & Limitations.

Ready to launch your first pass program?

Create your workspace, configure your pass template, and test a real pass in Apple Wallet and Google Wallet before you scale.