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:
Standaardschema voor foutantwoorden
{
"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 / reasonCode | HTTP- / Scanstatus | Oorzaak | Oplossing |
|---|---|---|---|
PASS_LIMIT_REACHED | 400 / 402 | De 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_SCAN | REJECTED (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_BALANCE | REJECTED (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_KEY | 401 / 403 | De 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-checkaan om gestructureerdeblockersenwarningste bekijken vóórPOST /api/v1/templates/:id/publish. -
Controleer Apple-ondertekening &
bundleId: Controleer of een geldig, niet-verlopen Apple Pass Type ID.p12-certificaat dat overeenkomt met debundleId(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 geldigchangeMessage(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/validatevoordat 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 voorserialNumberofexternalId.
Belangrijk: Noteer altijd de
requestIduit 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.
