Skip to content
Guida del Centro assistenza
3 min di letturaVerificato 2026-11-16

Risoluzione problemi e FAQ

Risolvi blocchi di pubblicazione, errori colonne CSV, discrepanze d'anteprima, ritardi push ed errori di scansione.

In questa guida

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:

FLUSSO ARCHITETTURALE
ARCHITETTURA INTERATTIVA
GESTIONE DELLE ECCEZIONI E LOCALIZZAZIONE
FASE 01 RICHIESTA IN INGRESSO (/api/v1/passes o /api/v1/scans, Accept-Language: de-DE)
FASE 02 SOLLEVATA ECCEZIONE DI DOMINIO / CONVALIDA
Allega errorCode strutturato e CLIENT_SAFE_EXTENSION_KEYS
FASE 03 API Error Handler GLOBALE E Error Catalog
Risolve il message localizzato da messageKey tramite Accept-Language
Inietta requestId, timestamp, path, retryAfter e details

Schema standard della risposta di errore

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

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 / reasonCodeStato HTTP / ScansioneCausa principaleSoluzione
PASS_LIMIT_REACHED400 / 402Il 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_SCANREJECTED (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_BALANCEREJECTED (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_KEY401 / 403L'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-check per ispezionare gli elenchi strutturati blockers e warnings prima di chiamare POST /api/v1/templates/:id/publish.
  • Verificare la prontezza della firma Apple e il bundleId: verifichi che un certificato .p12 Apple Pass Type ID valido e non scaduto, corrispondente al bundleId (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 un changeMessage valido (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/validate prima 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 con serialNumber o externalId duplicati.

Importante: Annoti sempre il requestId restituito 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.

Documentazione prodotto e API correlata

Pronto a lanciare il tuo primo programma di carte Wallet?

Crea il tuo workspace, configura il modello e testa una carta reale in Apple Wallet e Google Wallet prima di scalare.