Formato Padronizado de Erro da API
Todos os endpoints REST da Passinstance API formatam exceções através do filtro global API Error Handler. Quando uma chamada à API, configuração de webhook ou transação de leitura falha, analise a resposta JSON estruturada para identificar a causa exata e o requestId de correlação:
Esquema Padrão de Resposta de Erro
{
"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
}
]
}
Resoluções Comuns de errorCode
Consulte a tabela seguinte para resolver códigos de erro frequentes devolvidos em errorCode ou reasonCode in the scan response:
errorCode / reasonCode | Estado HTTP / Leitura | Causa Raiz | Resolução |
|---|---|---|---|
PASS_LIMIT_REACHED | 400 / 402 | O espaço de trabalho atingiu a quota de installedDevices do plano atual. | Atualize o plano via POST /api/v1/billing/subscription/change ou limpe cartões inativos. |
PASS_VOIDED_AFTER_SCAN | REJECTED (ALREADY_VOIDED) | Um cupão ou bilhete de utilização única (VOIDED_AFTER_SCAN scan mode) já foi resgatado. | Bloqueio antifraude esperado; consulte o estado anterior via GET /api/v1/scans/pass?barcode=... (correspondência por serialNumber ou externalId). |
OUT_OF_BALANCE | REJECTED (FAILED) | O débito de saldo pré-pago excede o montante restante com disallowNegativeBalance: true. | Carregue o saldo via /public/reload-sessions/:sessionId/initialize ou POST /api/v1/passes/:id/adjust-value. |
INVALID_SCANNER_KEY | 401 / 403 | O cabeçalho x-scanner-key está em falta, expirou ou foi revogado. | Verifique o estado da chave via GET /api/v1/scanner-keys/verify ou rode-a com POST /api/v1/scanner-keys/:id/rotate. |
Guia Rápido de Diagnóstico
1. O Modelo Não Publica
-
Execute a Verificação de Risco Pré-Publicação: Invoque
GET /api/v1/templates/:id/publish-risk-checkpara inspecionarblockersewarningsestruturados antes de chamarPOST /api/v1/templates/:id/publish. -
Verifique a Assinatura Apple e
bundleId: Confirme que existe um certificado.p12Apple Pass Type ID válido e não expirado correspondente aobundleId(passTypeIdentifier) do modelo atribuído ao espaço de trabalho (/api/v1/certificates). -
Verifique a Sintaxe de Cores e Códigos de Barras: Confirme a formatação
rgb(r, g, b)no Apple Wallet e garanta que os modelos de código de barras referenciam apenas chaves de campo existentes sem chavetas abertas.
2. A Atualização em Tempo Real Não Apareceu no Telemóvel
-
Verifique o Registo do Dispositivo: Apenas cartões com estado Ativo em Wallets (
installedDevices > 0) mantêm um canal push APNs ou Google Wallet ativo. Cartões não instalados (unclaimedPasses) não podem receber notificações push. -
Verifique a Alteração de Valor (
changeMessage): O Apple Wallet apresenta um alerta no ecrã bloqueado apenas quando um campo com umchangeMessageválido (incluindo%@) muda para um valor textual diferente. Guardar a mesma string suprime o alerta.
3. A Importação CSV em Lote Rejeitou Linhas
-
Valide o ficheiro CSV via
POST /api/v1/batch-processing/:id/validateantes de iniciar a execução (POST /api/v1/batch-processing/:id/start). Confirme a codificação UTF-8, alinhe os cabeçalhos das colunas com as chaves de campo do modelo e remova linhas duplicadas deserialNumberouexternalId.
Importante: Registe sempre o
requestIddevolvido no envelope JSON de erro (ex.:req_8f192b0e4c12) ao escalar uma ocorrência para Contactar o Suporte.
Explore mais respostas sobre a plataforma na Visão Geral de Suporte.
