Standardized API Error Envelope
Every REST endpoint in Passinstance API formats exceptions through the global API Error Handler. When an API call, webhook setup, or scanner transaction fails, inspect the structured JSON error response to pinpoint the exact root cause and correlation requestId:
Standard Error Response Schema
{
"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
}
]
}
Common errorCode Resolutions
Use the table below to resolve frequent domain error codes returned in errorCode or reasonCode in the scan response:
errorCode / reasonCode | HTTP / Scan Status | Root Cause | Resolution |
|---|---|---|---|
PASS_LIMIT_REACHED | 400 / 402 | Workspace has reached its plan's installedDevices quota. | Upgrade plan via POST /api/v1/billing/subscription/change or purge stale passes. |
PASS_VOIDED_AFTER_SCAN | REJECTED (ALREADY_VOIDED) | Single-use coupon or ticket (VOIDED_AFTER_SCAN scan mode) was already redeemed. | Expected anti-fraud block; inspect prior scan state via GET /api/v1/scans/pass?barcode=... (matching serialNumber or externalId). |
OUT_OF_BALANCE | REJECTED (FAILED) | Stored-value or prepaid redemption exceeds remaining balance with disallowNegativeBalance: true. | Reload pass balance via /public/reload-sessions/:sessionId/initialize or POST /api/v1/passes/:id/adjust-value. |
INVALID_SCANNER_KEY | 401 / 403 | The x-scanner-key header is missing, expired, or revoked. | Check key status via GET /api/v1/scanner-keys/verify or rotate via POST /api/v1/scanner-keys/:id/rotate. |
Quick Diagnostic Playbook
1. Template Will Not Publish
-
Run Pre-Publish Risk Check: Call
GET /api/v1/templates/:id/publish-risk-checkto inspect structuredblockersandwarningsbefore callingPOST /api/v1/templates/:id/publish. -
Check Apple Signing Readiness &
bundleId: Verify a valid, non-expired Apple Pass Type ID.p12certificate matching the template'sbundleId(passTypeIdentifier) is assigned to the workspace (/api/v1/certificates). -
Check Color & Barcode Syntax: Confirm Apple Wallet colors use
rgb(r, g, b)formatting and barcode message templates reference existing field keys without unclosed braces.
2. Live Card Update Did Not Appear on Phone
-
Verify Device Registration: Only passes flagged Active in Wallets (
installedDevices > 0) maintain an active APNs or Google Wallet push channel. Uninstalled cards (unclaimedPasses) cannot receive push alerts. -
Verify Value Mutation (
changeMessage): Apple Wallet displays a lock-screen banner only when a field containing a validchangeMessage(including%@) changes to a different string value. Saving the identical string suppresses the lock-screen alert.
3. CSV Batch Import Rejected Rows
-
Validate your CSV via
POST /api/v1/batch-processing/:id/validatebefore starting execution (POST /api/v1/batch-processing/:id/start). Confirm UTF-8 encoding, match header columns to template field keys, and remove duplicateserialNumberorexternalIdrows.
Important: Always record the
requestIdreturned in the error JSON envelope (e.g.req_8f192b0e4c12) when escalating an issue to Contact Support.
Browse additional platform answers in the Support Overview.
