Formato estándar de error de API
Todos los endpoints REST de Passinstance API devuelven las excepciones mediante el filtro global API Error Handler. Si falla una llamada a la API, una configuración de webhook o una transacción del escáner, revise la respuesta JSON estructurada para identificar la causa exacta y su requestId de correlación:
Esquema estándar de respuesta de error
{
"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
}
]
}
Resoluciones habituales de errorCode
Consulte esta tabla para resolver códigos de error frecuentes en errorCode o reasonCode in the scan response:
errorCode / reasonCode | Estado HTTP / Escaneo | Causa raíz | Resolución |
|---|---|---|---|
PASS_LIMIT_REACHED | 400 / 402 | El espacio de trabajo alcanzó el límite de installedDevices de su plan. | Amplíe su plan vía POST /api/v1/billing/subscription/change o depure pases inactivos. |
PASS_VOIDED_AFTER_SCAN | REJECTED (ALREADY_VOIDED) | Un cupón o entrada de un solo uso (VOIDED_AFTER_SCAN scan mode) ya fue canjeado. | Bloqueo antifraude esperado; revise el estado previo mediante GET /api/v1/scans/pass?barcode=... (coincidencia por serialNumber o externalId). |
OUT_OF_BALANCE | REJECTED (FAILED) | El cargo de valor almacenado o prepago supera el saldo disponible con disallowNegativeBalance: true. | Recargue saldo mediante /public/reload-sessions/:sessionId/initialize o POST /api/v1/passes/:id/adjust-value. |
INVALID_SCANNER_KEY | 401 / 403 | Falta la cabecera x-scanner-key, ha caducado o fue revocada. | Verifique la clave vía GET /api/v1/scanner-keys/verify o rótelo con POST /api/v1/scanner-keys/:id/rotate. |
Guía rápida de diagnóstico
1. La plantilla no se publica
-
Ejecute la comprobación previa de riesgos: Llame a
GET /api/v1/templates/:id/publish-risk-checkpara revisarblockersywarningsestructurados antes de llamar aPOST /api/v1/templates/:id/publish. -
Verifique firma Apple y
bundleId: Confirme que un certificado.p12Apple Pass Type ID vigente que coincida con elbundleId(passTypeIdentifier) de la plantilla está asignado al espacio de trabajo (/api/v1/certificates). -
Revise sintaxis de color y código de barras: Asegúrese de que Apple Wallet use formato
rgb(r, g, b)y de que los textos del código de barras referencien claves de campo reales sin llaves sin cerrar.
2. La actualización en vivo no aparece en el teléfono
-
Compruebe el registro del dispositivo: Solo los pases con estado Activo en Wallets (
installedDevices > 0) mantienen un canal push APNs o Google Wallet activo. Las tarjetas sin instalar (unclaimedPasses) no reciben avisos push. -
Compruebe el cambio de valor (
changeMessage): Apple Wallet muestra un aviso en pantalla bloqueada únicamente cuando un campo con unchangeMessageválido (con%@) cambia a una cadena distinta. Guardar el mismo texto suprime la notificación.
3. La importación CSV por lotes rechaza filas
-
Valide el CSV mediante
POST /api/v1/batch-processing/:id/validateantes de iniciar el proceso (POST /api/v1/batch-processing/:id/start). Verifique codificación UTF-8, alinee encabezados de columna con claves de campos de la plantilla y elimine duplicados deserialNumberoexternalId.
Importante: Anote siempre el
requestIddevuelto en la respuesta JSON de error (por ejemplo,req_8f192b0e4c12) al escalar una incidencia mediante Contactar con soporte.
Explore más respuestas sobre la plataforma en la Vista general de soporte.
