Busta di errore API standardizzata
Ogni endpoint REST in Passinstance API formatta le eccezioni tramite l'API Error Handler globale. Quando una chiamata API, la configurazione di un webhook o una transazione dello scanner non va a buon fine, ispezioni la risposta di errore JSON strutturata per individuare l'esatta causa principale e il requestId di correlazione:
Schema standard della risposta di errore
{
"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
}
]
}
Risoluzione dei codici errorCode più comuni
Utilizzi la tabella seguente per risolvere i codici di errore di dominio più frequenti restituiti in errorCode o reasonCode in the scan response:
errorCode / reasonCode | Stato HTTP / Scansione | Causa principale | Soluzione |
|---|---|---|---|
PASS_LIMIT_REACHED | 400 / 402 | Il workspace ha raggiunto la quota installedDevices prevista dal proprio piano. | Effettui l'upgrade del piano tramite POST /api/v1/billing/subscription/change oppure elimini i pass obsoleti. |
PASS_VOIDED_AFTER_SCAN | REJECTED (ALREADY_VOIDED) | Un coupon o biglietto monouso (VOIDED_AFTER_SCAN scan mode) è già stato riscattato. | Blocco antifrode previsto; ispezioni lo stato della scansione precedente tramite GET /api/v1/scans/pass?barcode=... (corrispondente a serialNumber o externalId). |
OUT_OF_BALANCE | REJECTED (FAILED) | Il riscatto su carta prepagata o a valore memorizzato supera il saldo residuo con disallowNegativeBalance: true. | Ricarichi il saldo del pass tramite /public/reload-sessions/:sessionId/initialize o POST /api/v1/passes/:id/adjust-value. |
INVALID_SCANNER_KEY | 401 / 403 | L'header x-scanner-key è mancante, scaduto o revocato. | Verifichi lo stato della chiave tramite GET /api/v1/scanner-keys/verify oppure la ruoti tramite POST /api/v1/scanner-keys/:id/rotate. |
Manuale diagnostico rapido
1. Il modello non viene pubblicato
-
Eseguire il controllo dei rischi pre-pubblicazione: chiami
GET /api/v1/templates/:id/publish-risk-checkper ispezionare gli elenchi strutturatiblockersewarningsprima di chiamarePOST /api/v1/templates/:id/publish. -
Verificare la prontezza della firma Apple e il
bundleId: verifichi che un certificato.p12Apple Pass Type ID valido e non scaduto, corrispondente albundleId(passTypeIdentifier) del modello, sia assegnato al workspace (/api/v1/certificates). -
Verificare la sintassi dei colori e del codice a barre: confermi che i colori di Apple Wallet utilizzino il formato
rgb(r, g, b)e che i modelli di messaggio del codice a barre facciano riferimento a chiavi di campo esistenti senza parentesi graffe non chiuse.
2. L'aggiornamento di una carta attiva non è apparso sullo smartphone
-
Verificare la registrazione del dispositivo: solo i pass contrassegnati come Attivi nei Wallet (
installedDevices > 0) mantengono un canale push attivo APNs o Google Wallet. Le carte non installate (unclaimedPasses) non possono ricevere avvisi push. -
Verificare la modifica effettiva del valore (
changeMessage): Apple Wallet mostra un banner sulla schermata di blocco solo quando un campo contenente unchangeMessagevalido (incluso%@) passa a un valore stringa differente. Il salvataggio della stessa identica stringa sopprime l'avviso sulla schermata di blocco.
3. L'importazione batch CSV ha rifiutato alcune righe
-
Convalidi il file CSV tramite
POST /api/v1/batch-processing/:id/validateprima di avviare l'esecuzione (POST /api/v1/batch-processing/:id/start). Confermi la codifica UTF-8, faccia corrispondere le colonne di intestazione alle chiavi dei campi del modello e rimuova le righe conserialNumberoexternalIdduplicati.
Importante: Annoti sempre il
requestIdrestituito nella busta JSON di errore (ad es.req_8f192b0e4c12) quando segnala un problema tramite Contattare il supporto.
Consulti ulteriori risposte sulla piattaforma nella Panoramica del supporto.
