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

Troubleshooting & FAQs

Solve common publishing blockers, CSV mapping errors, wallet preview mismatches, notification delays, and scanner validation errors.

In This Guide

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:

SYSTEM ARCHITECTURE FLOW
INTERACTIVE ARCHITECTURE
EXCEPTION HANDLING & LOCALIZATION
STAGE 01 INCOMING REQUEST (/api/v1/passes or /api/v1/scans, Accept-Language: de-DE)
STAGE 02 DOMAIN / VALIDATION EXCEPTION THROWN
Attaches structured errorCode & CLIENT_SAFE_EXTENSION_KEYS
STAGE 03 STANDARDIZED API ERROR HANDLER
Resolves localized message from messageKey via Accept-Language
Injects requestId, timestamp, path, retryAfter, and details

Standard Error Response Schema

JSON
{
  "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 / reasonCodeHTTP / Scan StatusRoot CauseResolution
PASS_LIMIT_REACHED400 / 402Workspace has reached its plan's installedDevices quota.Upgrade plan via POST /api/v1/billing/subscription/change or purge stale passes.
PASS_VOIDED_AFTER_SCANREJECTED (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_BALANCEREJECTED (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_KEY401 / 403The 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-check to inspect structured blockers and warnings before calling POST /api/v1/templates/:id/publish.
  • Check Apple Signing Readiness & bundleId: Verify a valid, non-expired Apple Pass Type ID .p12 certificate matching the template's bundleId (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 valid changeMessage (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/validate before starting execution (POST /api/v1/batch-processing/:id/start). Confirm UTF-8 encoding, match header columns to template field keys, and remove duplicate serialNumber or externalId rows.

Important: Always record the requestId returned in the error JSON envelope (e.g. req_8f192b0e4c12) when escalating an issue to Contact Support.

Browse additional platform answers in the Support Overview.

Related Product & Developer Documentation

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.