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.
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 Header | Description |
|---|---|
RateLimit-Limit / X-RateLimit-Limit | Maximum requests allowed within the current 1-second burst window. |
RateLimit-Remaining / X-RateLimit-Remaining | Remaining requests permitted in the active window before throttling. |
RateLimit-Reset / X-RateLimit-Reset | Seconds remaining until the rate-limit bucket resets. |
Retry-After | Seconds to wait before retrying after receiving an HTTP 429 response. |
HTTP 429 Throttled Response Payload:
{
"error": "Rate limit exceeded",
"retryAfter": 1
}
Request Payload & Idempotency Constraints
-
Maximum Request Body (
10MB): The API gateway enforces a strict10MBpayload 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(oridempotencyKeyinPOST /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, orexternalId.
Platform-Level Wallet Constraints (Apple & Google)
Several behavioral boundaries originate directly from Apple iOS and Google Android operating system architectures:
| Constraint | Platform | Technical 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 Caching | Google Wallet vs. Apple Wallet | Apple 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 Suppression | Apple Wallet | iOS 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 Registration | Apple Wallet + watchOS | A 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 Blocking | iOS Instagram, TikTok, LinkedIn | Embedded 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 Hardware | Encrypted 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.
