Skip to content
Guía del Centro de ayuda
3 min de lecturaVerificado 2026-11-16

Solución de problemas y preguntas frecuentes

Resuelve bloqueos al publicar, errores de columnas CSV, discrepancias de vista previa y retrasos push.

En esta guía

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:

FLUJO DE ARQUITECTURA
ARQUITECTURA INTERACTIVA
GESTIÓN DE EXCEPCIONES Y LOCALIZACIÓN
ETAPA 01 SOLICITUD ENTRANTE (/api/v1/passes o /api/v1/scans, Accept-Language: es-ES)
ETAPA 02 EXCEPCIÓN DE DOMINIO / VALIDACIÓN LANZADA
Adjunta errorCode estructurado y CLIENT_SAFE_EXTENSION_KEYS
ETAPA 03 API Error Handler GLOBAL Y Error Catalog
Resuelve el mensaje message según messageKey y Accept-Language
Añade requestId, timestamp, path, retryAfter y details

Esquema estándar de respuesta de error

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

Resoluciones habituales de errorCode

Consulte esta tabla para resolver códigos de error frecuentes en errorCode o reasonCode in the scan response:

errorCode / reasonCodeEstado HTTP / EscaneoCausa raízResolución
PASS_LIMIT_REACHED400 / 402El 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_SCANREJECTED (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_BALANCEREJECTED (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_KEY401 / 403Falta 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-check para revisar blockers y warnings estructurados antes de llamar a POST /api/v1/templates/:id/publish.
  • Verifique firma Apple y bundleId: Confirme que un certificado .p12 Apple Pass Type ID vigente que coincida con el bundleId (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 un changeMessage vá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/validate antes 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 de serialNumber o externalId.

Importante: Anote siempre el requestId devuelto 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.

Documentación de producto y API relacionada

¿Listo para lanzar su primer programa de tarjetas Wallet?

Cree su espacio de trabajo, configure su plantilla y pruebe una tarjeta real en Apple Wallet y Google Wallet antes de escalar.