Erros

Tabela completa de códigos de erro, classes e tratamento recomendado.

Princípios de tratamento

Programático: use instanceof (Web) ou when/switch por tipo (Android/iOS) para tratamento específico
Código numérico: use error.code (Web) ou error.type (nativos) para tratamento granular
Serialização: error.toJSON() (Web) retorna objeto sem stack trace — seguro para telemetria
Causa raiz: error.cause (Web) ou error.exception (Android) preserva o erro original

Web SDK — Códigos numéricos

Código	Constante	Classe	Quando ocorre
1000	`UNKNOWN`	`ProvviError`	Erro genérico não classificado
2001	`CAMERA_NOT_SUPPORTED`	`ProvviUserAgentError`	Browser não suporta `getUserMedia`
3001	`STREAM_OPEN_FAILED`	`ProvviStreamError`	Falha ao abrir câmera (permissão negada, câmera em uso)
3002	`STREAM_CAPTURE_FAILED`	`ProvviStreamError`	Falha ao capturar frame (canvas, encoding JPEG)
4001	`SESSION_FETCH_FAILED`	`ProvviAPIError`	Sessão não encontrada, expirada ou já capturada
4002	`INGEST_FAILED`	`ProvviAPIError`	Erro no envio da captura (rejeição do servidor)
5001	`CAPTURE_FAILED`	`ProvviCaptureError`	Erro na orquestração do pipeline
5002	`TOKEN_REQUIRED`	`ProvviCaptureError`	`open()` chamado sem token
6001	`GPS_UNAVAILABLE`	`ProvviGeolocationError`	API de geolocalização não disponível
6002	`GPS_DENIED`	`ProvviGeolocationError`	Usuário negou permissão de localização
6003	`GPS_TIMEOUT`	`ProvviGeolocationError`	Timeout na aquisição de GPS
7001	`UPLOAD_FAILED`	`ProvviUploadError`	Falha no upload da captura
8001	`LICENSE_KEY_MISSING`	`ProvviLicenseError`	`licenseKey` não informada
8002	`LICENSE_INVALID`	`ProvviLicenseError`	Licença rejeitada — código genérico, ver `details.reason` abaixo
8003	`LICENSE_NETWORK_ERROR`	`ProvviLicenseError`	Falha de rede na validação

Código 8002 — reasons detalhados

O código LICENSE_INVALID (8002) cobre múltiplas situações. O motivo específico é acessível via error.details.reason (Web) ou pelo campo reason na resposta de /validate:

`details.reason`	Situação
`INVALID_KEY`	Chave não encontrada no banco
`REVOKED`	Licença desativada pelo administrador
`EXPIRED`	Contrato expirado
`VOLUME_EXCEEDED`	Limite mensal de capturas atingido
`CLIENT_SUSPENDED`	Conta do cliente suspensa
`PACKAGE_NOT_ALLOWED`	Bundle/package não autorizado para esta licença

Tratamento Web SDK

import { EVENTS, ProvviLicenseError, ProvviStreamError, CODES } from 'provvi-camera.es.js';

camera.addEventListener(EVENTS.ERROR, (e) => {
  const err = e.detail.error;

  // Por classe
  if (err instanceof ProvviLicenseError) {
    // err.details.reason → INVALID_KEY, REVOKED, EXPIRED, etc.
    showLicenseError(err.details.reason);
    return;
  }

  if (err instanceof ProvviStreamError) {
    showCameraError(err.message);
    return;
  }

  // Por código numérico
  switch (err.code) {
    case CODES.TOKEN_REQUIRED:
      console.error('Token não fornecido');
      break;
    case CODES.GPS_DENIED:
      showGpsWarning();
      break;
    default:
      reportToSentry(err.toJSON());
  }
});

Android SDK — Tipos de erro

ProvviErrorType (via ProvviResult)

Tipo	Descrição	Recuperável
Permissões
`PERMISSION_DENIED`	Câmera ou localização negada	Sim — solicitar novamente
Integridade
`DEVICE_COMPROMISED`	Root/emulador detectado	Não
`STRONGBOX_UNAVAILABLE`	StrongBox ausente (não bloqueante)	N/A
`ATTESTATION_ERROR`	Play Integrity API inacessível	Sim — retry
Câmera
`CAMERA_NOT_FOUND`	Sem câmera física	Não
`CAMERA_IN_USE`	Câmera em uso por outro app	Sim — fechar outro app
`CAMERA_TIMEOUT`	Sem frame em 10 segundos	Sim — retry
`CAMERA_ERROR`	Erro genérico de câmera	Sim — retry
Localização
`MOCK_LOCATION_DETECTED`	GPS falso detectado	Não
`LOCATION_UNAVAILABLE`	Sem fonte de localização	Depende do perfil
Recaptura
`RECAPTURE_SUSPECTED`	Foto de tela detectada	Não
Assinatura
`SIGNING_FAILED`	Falha C2PA (c2pa-rs)	Sim — retry
`MANIFEST_INVALID`	Manifesto corrompido	Sim — retry
`FRAME_HASH_FAILED`	Falha SHA-256	Sim — retry
Rede
`NETWORK_UNAVAILABLE`	Sem conectividade	Sim — verificar rede
`BACKEND_UNAVAILABLE`	Upload falhou	Sim — retry via `retryUpload()`
`BACKEND_AUTH_FAILED`	API Key inválida (401)	Verificar credenciais
`BACKEND_TIMEOUT`	Timeout no upload	Sim — retry
`TSA_UNAVAILABLE`	Timestamp Authority offline	Sim — retry automático (3x)
Relógio
`CLOCK_SUSPICIOUS`	Drift > 300s (cliente) ou > 600s (servidor)	Não
Licenciamento
`LICENSE_KEY_MISSING`	`licenseKey` vazio no config	Configurar a chave
`LICENSE_NOT_VALIDATED`	`validateLicense()` não chamado	Chamar antes de `capture()`
`LICENSE_INVALID`	Chave não reconhecida	Verificar no Admin Console
`LICENSE_REVOKED`	Licença revogada	Contatar Provvi
`LICENSE_EXPIRED`	Contrato expirado	Renovar contrato
`LICENSE_VOLUME_EXCEEDED`	Limite mensal atingido	Ampliar volume
`LICENSE_NETWORK_ERROR`	Sem rede para validar	Verificar conexão
`LICENSE_CLIENT_SUSPENDED`	Conta suspensa	Contatar Provvi
`LICENSE_PACKAGE_NOT_ALLOWED`	Package não autorizado	Verificar licença
Genérico
`UNKNOWN`	Erro não classificado	Depende

Tratamento Android

when (outcome) {
    is CaptureOutcome.LicenseError -> {
        when (outcome.error.type) {
            ProvviErrorType.LICENSE_EXPIRED -> showRenewDialog()
            ProvviErrorType.LICENSE_VOLUME_EXCEEDED -> showUpgradeDialog()
            ProvviErrorType.LICENSE_REVOKED -> blockCapture()
            else -> showGenericError(outcome.error.message)
        }
    }
    is CaptureOutcome.BackendError -> {
        when (outcome.errorType) {
            BackendErrorType.TSA_UNAVAILABLE -> scheduleRetry(outcome.result)
            BackendErrorType.AUTH_FAILED -> checkCredentials()
            else -> showRetryDialog(outcome.message)
        }
    }
    // ...
}

iOS SDK — Erros de licença

Caso	Enum	Descrição
Chave vazia	`.keyMissing`	`licenseKey` não configurado
Chave inválida	`.invalidKey("INVALID_KEY")`	Não encontrada no backend
Revogada	`.invalidKey("REVOKED")`	Desativada pelo admin
Expirada	`.invalidKey("EXPIRED")`	Contrato vencido
Volume excedido	`.invalidKey("VOLUME_EXCEEDED")`	Limite mensal
Conta suspensa	`.invalidKey("CLIENT_SUSPENDED")`	Cliente suspenso
Rede	`.networkError(error)`	Falha de rede + sem cache válido

Tratamento iOS

switch outcome {
case .licenseError(let reason):
    switch reason {
    case "EXPIRED": showRenewDialog()
    case "VOLUME_EXCEEDED": showUpgradeDialog()
    case "REVOKED", "CLIENT_SUSPENDED": blockCapture()
    default: showAlert("Licença: \(reason)")
    }

case .backendError(let message, let session):
    if let session = session {
        // Captura local OK — agendar retry
        scheduleRetry(session)
    }

case .deviceCompromised:
    showAlert("Dispositivo comprometido. Captura bloqueada.")

// ...
}

API Backend — Erros HTTP

HTTP	Endpoint	Causa	Body
400	`/web/sessions`	Payload inválido	`{ "error": "Payload inválido: ..." }`
400	`/web/sessions`	Profile inválido	`{ "error": "profile inválido — use: ..." }`
400	`/web/ingest`	Imagem estática	`{ "error": "Imagem estática detectada..." }`
401	`/web/sessions`	API Key inválida	`{ "error": "API key inválida ou ausente" }`
403	`/web/ingest`	Clock drift > 600s	`{ "error": "Relógio do dispositivo fora de sincronia..." }`
404	`/web/sessions/:token`	Sessão não encontrada	`{ "error": "Sessão não encontrada" }`
409	`/web/ingest`	Hash duplicado (replay)	`{ "error": "Imagem duplicada detectada na sessão" }`
410	`/web/sessions/:token`	Sessão expirada	`{ "error": "Sessão expirada ou já utilizada" }`
502	`/web/ingest`	Erro na assinatura	`{ "error": "Erro de assinatura: ..." }`

Licenciamento — Razões de rejeição

Quando /validate retorna { "valid": false, "reason": "..." }:

Reason	Descrição	Ação recomendada
`INVALID_KEY`	Chave não encontrada no banco	Verificar chave no Admin Console
`REVOKED`	Licença desativada pelo admin	Contatar Provvi
`EXPIRED`	Data de expiração do contrato ultrapassada	Renovar contrato
`VOLUME_EXCEEDED`	Capturas excederam o limite mensal	Aguardar reset ou ampliar volume
`CLIENT_SUSPENDED`	Conta do cliente suspensa	Contatar Provvi
`PACKAGE_NOT_ALLOWED`	Bundle/package não está na whitelist	Registrar package no Admin Console