Códigos de Erro

Erros do SDK (SurtError)

Erro	Quando
notInitialized	verify() chamado antes de initialize()
invalidJwt	JWT ausente, malformado ou rejeitado pelo backend. Gere um JWT novo a cada verify().
networkError	Timeout ou sem conexão
serverError	5xx do backend
attestationFailed	Falha na verificação de integridade do dispositivo — geralmente um JWT reutilizado. Gere um JWT novo a cada verify().

As plataformas nativas expõem estes como .notInitialized / .invalidJwt / etc. A ponte do React Native expõe códigos em string: not_initialized, invalid_jwt, attestation_failed, network_error.

Web SDK errors

O SDK Web (@surtai/guardian-web) usa um GuardianError separado com os códigos CRYPTO_UNAVAILABLE, ENCRYPTION_FAILED e INVALID_OPTIONS. Veja Pacote NPM.

Diagnóstico do resultado

Todo resultado de verify() e collect() inclui um objeto diagnostics. Você o lê diretamente do resultado que já recebe — é aditivo, então o código existente não é afetado. A forma é idêntica em Web, iOS, Android e React Native.

// React Native (verify) — diagnostics está no resultado que você já recebe
const result = await GuardianSDK.verify(jwt);
console.log(result.diagnostics?.location);     // ex.: "denied"
console.log(result.diagnostics?.warnings);     // ex.: [{ code: "LOCATION_PERMISSION_DENIED", signal: "location" }]

// Web (collect) — diagnostics fica junto ao payload
const { payload, diagnostics } = await collect({ collectLocation: true });
console.log(diagnostics.location);

// iOS (Swift) — no VerificationResult / CollectResult
let result = try await GuardianSDK.shared.verify(jwt: jwt)
print(result.diagnostics.location ?? "n/a")

// Android (Kotlin) — no VerificationResult / CollectResult
val result = GuardianSDK.getInstance().verifySuspend(jwt).getOrThrow()
Log.d("Guardian", result.diagnostics.location ?: "n/a")

Campo	Valores	Significado
location	collected · denied · unavailable · timeout · not_requested	Se a localização do dispositivo foi capturada, ou por que não (ex.: o usuário negou a permissão).
networkIntel	collected · unavailable · not_requested	Se o sinal complementar de inteligência de rede esteve disponível nesta transação.
warnings	array de { code, signal, detail? }	Notas estruturadas e não fatais que você pode registrar ou mostrar ao suporte (ex.: LOCATION_PERMISSION_DENIED).

{
  "diagnostics": {
    "location": "denied",
    "networkIntel": "collected",
    "warnings": [{ "code": "LOCATION_PERMISSION_DENIED", "signal": "location" }]
  }
}

dica

Use diagnostics para explicar resultados aos seus usuários ou à equipe de suporte — por exemplo, pedindo ao usuário para ativar a localização quando location for denied.

Códigos de Status HTTP

Código	Significado
200	Sucesso
400	JSON malformado ou campo obrigatório ausente
401	Bearer JWT inválido ou ausente
403	Chave válida mas sem permissão
5xx	Erro do servidor