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 :
Schéma standard de réponse d'erreur
{
"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 / reasonCode | Statut HTTP / Scan | Cause racine | Résolution |
|---|---|---|---|
PASS_LIMIT_REACHED | 400 / 402 | L'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_SCAN | REJECTED (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_BALANCE | REJECTED (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_KEY | 401 / 403 | L'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-checkpour consulter lesblockersetwarningsavantPOST /api/v1/templates/:id/publish. -
Vérifier la signature Apple & le
bundleId: Vérifiez qu'un certificat.p12Apple Pass Type ID valide correspondant aubundleId(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 unchangeMessagevalide (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/validateavant 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 deserialNumberouexternalId.
Important : Relevez systématiquement le
requestIdrenvoyé 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.
