Skip to content
Helpcentrum-gids
2 min leestijdGecontroleerd 2026-11-16

Probleemoplossing & veelgestelde vragen

Los veelvoorkomende publicatieblokkades, CSV-fouten, voorbeeldfouten, pushvertragingen en scancodes op.

In deze gids

Gestandaardiseerd API-foutformaat

Elke REST-endpoint in Passinstance API formatteert uitzonderingen via het globale API Error Handler. Wanneer een API-aanroep, webhook-configuratie of scannertransactie mislukt, controleer dan het gestructureerde JSON-foutantwoord voor de exacte oorzaak en correlatie-requestId:

SYSTEEMARCHITECTUUR
INTERACTIEVE ARCHITECTUUR
FOUTAFHANDELING & LOKALISATIE
FASE 01 INKOMEND VERZOEK (/api/v1/passes of /api/v1/scans, Accept-Language: nl-NL)
FASE 02 DOMEIN- / VALIDATIEFOUT OPGETREDEN
Voegt gestructureerde errorCode & CLIENT_SAFE_EXTENSION_KEYS toe
FASE 03 GLOBAAL API Error Handler & Error Catalog
Haalt gelokaliseerde message op via messageKey en Accept-Language
Voegt requestId, timestamp, path, retryAfter en details toe

Standaardschema voor foutantwoorden

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
    }
  ]
}

Oplossingen voor veelvoorkomende errorCode-waarden

Gebruik onderstaande tabel om frequente domeinfoutcodes in errorCode of reasonCode in the scan response op te lossen:

errorCode / reasonCodeHTTP- / ScanstatusOorzaakOplossing
PASS_LIMIT_REACHED400 / 402De werkruimte heeft de limiet voor installedDevices van het abonnement bereikt.Upgrade het abonnement via POST /api/v1/billing/subscription/change of ruim inactieve passen op.
PASS_VOIDED_AFTER_SCANREJECTED (ALREADY_VOIDED)Een eenmalige coupon of toegangsticket (VOIDED_AFTER_SCAN scan mode) is al verzilverd.Verwachte fraudeblokkering; bekijk de eerdere scanstatus via GET /api/v1/scans/pass?barcode=... (serialNumber of externalId).
OUT_OF_BALANCEREJECTED (FAILED)Afschrijving van opgeslagen waarde of prepaidtegoed overschrijdt het restsaldo bij disallowNegativeBalance: true.Laad het passaldo op via /public/reload-sessions/:sessionId/initialize of POST /api/v1/passes/:id/adjust-value.
INVALID_SCANNER_KEY401 / 403De header x-scanner-key ontbreekt, is verlopen of is ingetrokken.Controleer de sleutelstatus via GET /api/v1/scanner-keys/verify of roteer via POST /api/v1/scanner-keys/:id/rotate.

Snelle diagnosehandleiding

1. Sjabloon kan niet worden gepubliceerd

  • Voer risicocontrole vóór publicatie uit: Roep GET /api/v1/templates/:id/publish-risk-check aan om gestructureerde blockers en warnings te bekijken vóór POST /api/v1/templates/:id/publish.
  • Controleer Apple-ondertekening & bundleId: Controleer of een geldig, niet-verlopen Apple Pass Type ID .p12-certificaat dat overeenkomt met de bundleId (passTypeIdentifier) van het sjabloon aan de werkruimte is gekoppeld (/api/v1/certificates).
  • Controleer kleur- & barcodesyntaxis: Bevestig dat Apple Wallet-kleuren rgb(r, g, b) gebruiken en dat barcode-berichtsjablonen naar bestaande veldsleutels verwijzen zonder ongesloten accolades.

2. Live kaartupdate verschijnt niet op de telefoon

  • Controleer apparaatregistratie: Alleen passen met status Actief in Wallets (installedDevices > 0) beschikken over een actief APNs- of Google Wallet-pushkanaal. Niet-geïnstalleerde kaarten (unclaimedPasses) kunnen geen pushmeldingen ontvangen.
  • Controleer waardewijziging (changeMessage): Apple Wallet toont alleen een melding op het toegangsscherm wanneer een veld met een geldig changeMessage (inclusief %@) wijzigt naar een andere tekenreekswaarde. Het opslaan van een identieke waarde onderdrukt de melding.

3. CSV-batchimport weigert rijen

  • Valideer uw CSV via POST /api/v1/batch-processing/:id/validate voordat u de uitvoering start (POST /api/v1/batch-processing/:id/start). Controleer UTF-8-codering, koppel kolomkoppen aan de veldsleutels van het sjabloon en verwijder dubbele rijen voor serialNumber of externalId.

Belangrijk: Noteer altijd de requestId uit het JSON-foutbericht (bijv. req_8f192b0e4c12) wanneer u een melding escaleert naar Contact opnemen met support.

Bekijk meer antwoorden over het platform in het Supportoverzicht.

Gerelateerde product- en ontwikkelaarsdocs

Klaar om uw eerste kaartprogramma te lanceren?

Maak uw workspace aan, configureer uw sjabloon en test een echte kaart in Apple Wallet en Google Wallet voordat u opschaalt.