Skip to content
Guide du centre d'aide
3 min de lectureVérifié 2026-11-16

Dépannage & FAQ

Résolvez les blocages de publication, erreurs d'import CSV, écarts d'aperçu, délais push et rejets de scan.

Dans ce guide

Format d'erreur API standardisé

Chaque endpoint REST de Passinstance API formate les exceptions via le filtre global API Error Handler. Lorsqu'un appel API, une configuration webhook ou une transaction de scanner échoue, examinez la réponse JSON structurée pour identifier la cause exacte et le requestId de corrélation :

FLUX ARCHITECTURE SYSTÈME
ARCHITECTURE INTERACTIVE
FLUX D'ARCHITECTURE : GESTION DES EXCEPTIONS & LOCALISATION
ÉTAPE 01 REQUÊTE ENTRANTE (/api/v1/passes ou /api/v1/scans, Accept-Language: fr-FR)
ÉTAPE 02 EXCEPTION MÉTIER / DE VALIDATION LEVÉE
Attache errorCode structuré & CLIENT_SAFE_EXTENSION_KEYS
ÉTAPE 03 API Error Handler GLOBAL & Error Catalog
Résout le texte message depuis messageKey via Accept-Language
Injecte requestId, timestamp, path, retryAfter et details

Schéma standard de réponse d'erreur

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

Résolutions courantes des errorCode

Utilisez le tableau ci-dessous pour résoudre les codes d'erreur métier retournés dans errorCode ou reasonCode in the scan response :

errorCode / reasonCodeStatut HTTP / ScanCause racineRésolution
PASS_LIMIT_REACHED400 / 402L'espace de travail a atteint le quota installedDevices du forfait.Passez à un forfait supérieur via POST /api/v1/billing/subscription/change ou purgez les cartes obsolètes.
PASS_VOIDED_AFTER_SCANREJECTED (ALREADY_VOIDED)Coupon ou billet à usage unique (VOIDED_AFTER_SCAN scan mode) déjà validé.Blocage antifraude attendu ; consultez l'état précédent via GET /api/v1/scans/pass?barcode=... (correspondance par serialNumber ou externalId).
OUT_OF_BALANCEREJECTED (FAILED)Le débit de carte prépayée dépasse le solde restant avec disallowNegativeBalance: true.Rechargez la carte via /public/reload-sessions/:sessionId/initialize ou POST /api/v1/passes/:id/adjust-value.
INVALID_SCANNER_KEY401 / 403L'en-tête x-scanner-key est absent, expiré ou révoqué.Vérifiez la clé via GET /api/v1/scanner-keys/verify ou faites-la tourner avec POST /api/v1/scanner-keys/:id/rotate.

Guide de diagnostic rapide

1. Le modèle refuse d'être publié

  • Exécuter le contrôle de risque pré-publication : Appelez GET /api/v1/templates/:id/publish-risk-check pour consulter les blockers et warnings avant POST /api/v1/templates/:id/publish.
  • Vérifier la signature Apple & le bundleId : Vérifiez qu'un certificat .p12 Apple Pass Type ID valide correspondant au bundleId (passTypeIdentifier) du modèle est affecté à l'espace de travail (/api/v1/certificates).
  • Vérifier les couleurs et codes-barres : Confirmez le format rgb(r, g, b) pour Apple Wallet et l'absence d'accolades non fermées ou de clés de champ inexistantes dans le modèle du code-barres.

2. La mise à jour en direct n'apparaît pas sur le téléphone

  • Vérifier l'enregistrement de l'appareil : Seules les cartes Actives dans les Wallets (installedDevices > 0) disposent d'un canal push APNs ou Google Wallet actif. Les cartes non installées (unclaimedPasses) ne reçoivent pas de notification push.
  • Vérifier la modification de valeur (changeMessage) : Apple Wallet n'affiche une bannière sur l'écran verrouillé que lorsqu'un champ portant un changeMessage valide (contenant %@) change vers une chaîne différente. Enregistrer la même chaîne supprime l'alerte.

3. L'import CSV par lots rejette des lignes

  • Validez votre fichier CSV via POST /api/v1/batch-processing/:id/validate avant de lancer l'exécution (POST /api/v1/batch-processing/:id/start). Vérifiez l'encodage UTF-8, alignez les en-têtes sur les clés de champs du modèle et supprimez les doublons de serialNumber ou externalId.

Important : Relevez systématiquement le requestId renvoyé dans l'enveloppe d'erreur JSON (par ex. req_8f192b0e4c12) avant de solliciter Contacter le support.

Parcourez d'autres réponses sur la plateforme dans la Vue d'ensemble du support.

Documentation produit et développeur associée

Prêt à lancer votre premier programme de cartes Wallet ?

Créez votre espace de travail, configurez votre modèle et testez une vraie carte dans Apple Wallet et Google Wallet avant de déployer à grande échelle.