Pular para o conteúdo principal
Versão: Guardian v0.5.3

Códigos de Erro

Erros do SDK (SurtError)​

Cada plataforma reporta uma falha de verify() ou collect() à sua maneira.

iOS​

verify() e collect() falham com um SurtError.

ErroQuando
.notInitializedverify() ou collect() chamado antes de GuardianSDK.initialize()
.networkError(Error)Qualquer outra falha: sem conexão, tempo esgotado ou um erro HTTP da Surt. O erro associado descreve a causa.

SurtError também declara .noCustomer, .invalidApiKey, .serverError e .attestationFailed. O SDK não os retorna nesta versão.

Android​

ErroQuando
IllegalStateException (lançada)GuardianSDK.getInstance() chamado antes de GuardianSDK.initialize()
java.io.IOException (no Result)verify() recebeu um erro HTTP da Surt, ou a requisição não foi concluída. Para um erro HTTP, a mensagem começa com HTTP <status>.
SurtError.NetworkError (no Result)Um erro inesperado dentro do SDK. underlying contém a causa. collect() reporta toda falha dessa forma.

verifySuspend() e collectSuspend() retornam um Result do Kotlin. Chame .getOrThrow() ou trate onSuccess e onFailure.

Nas duas plataformas, o SDK envia a requisição de verify() até 3 vezes antes de retornar uma falha.

React Native​

verify() e collect() rejeitam com um erro que tem um code e uma message. A message é uma string JSON com seus próprios code e message.

Plataformaerror.codecode dentro de error.message
iOSverification_failed em verify(), collect_failed em collect()not_initialized ou network_error
Androidverification_failed em verify(), collect_failed em collect(), sdk_error para um erro inesperadoMesmo valor de error.code
try {
const result = await verify(jwt);
} catch (e: any) {
let detail: { code?: string; message?: string } = {};
try {
detail = JSON.parse(e.message);
} catch {
// message was not JSON
}
console.warn(e.code, detail.code, detail.message);
}
Erros do SDK web

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 que descreve o que o SDK observou durante a transação. O código existente que não o lê não é afetado. O React Native o retorna a partir da v0.5.2. Alguns campos existem apenas em algumas plataformas, como mostra a tabela.

// React Native (verify): diagnostics is on the result you already receive
const result = await GuardianSDK.verify(jwt);
console.log(result.diagnostics?.location); // e.g. "denied"
console.log(result.diagnostics?.warnings); // e.g. [{ code: "LOCATION_PERMISSION_DENIED", signal: "location" }]

// Web (collect): diagnostics sits alongside the payload
const { payload, diagnostics } = await collect({ collectLocation: true });
console.log(diagnostics.location);
// iOS (Swift): on the VerificationResult / CollectResult
let result = try await GuardianSDK.shared.verify(jwt: jwt)
print(result.diagnostics.location ?? "n/a")
// Android (Kotlin): on the VerificationResult / CollectResult
val result = GuardianSDK.getInstance().verifySuspend(jwt).getOrThrow()
Log.d("Guardian", result.diagnostics.location ?: "n/a")
CampoPlataformasValoresSignificado
locationTodascollected · denied · unavailable · timeout · not_requested · errorSe a localização do dispositivo foi capturada, ou por que não (por exemplo, o usuário negou a permissão).
attestationiOS, Android, React Nativecollected · failed · unavailable · not_supported · not_requestedSe o dispositivo produziu uma atestação (App Attest no iOS, Play Integrity no Android). O collect() do Android também retorna skipped quando a atestação não era devida nesta transação.
networkIntelTodascollected · unavailable · not_requestedSe o sinal complementar de inteligência de rede estava disponível para esta transação.
timingsTodos (iOS a partir da v0.5.3)objeto com os milissegundos por fase, mais totalTempo gasto em cada fase da chamada.
warningsTodasarray de { code, signal, detail? }Avisos não fatais que você pode registrar em log ou mostrar ao suporte. Sempre presente, possivelmente vazio.

No Android, location é collected quando o app tem a permissão de localização, mesmo que o dispositivo não tivesse uma localização para reportar.

Códigos de aviso​

CódigosignalPlataformasSignificado
LOCATION_PERMISSION_DENIEDlocationTodasO usuário negou a permissão de localização.
LOCATION_UNAVAILABLElocationiOS, WebA localização foi solicitada, mas nenhuma posição foi obtida.
LOCATION_TIMEOUTlocationWebO navegador não retornou uma posição a tempo.
LOCATION_ERRORlocationWebA API de Geolocalização do navegador falhou.
ATTESTATION_FAILEDattestationiOS, AndroidA atestação foi tentada e falhou.
ATTESTATION_UNAVAILABLEattestationiOS, AndroidA atestação não está disponível neste dispositivo.
ATTESTATION_NOT_SUPPORTEDattestationAndroidO dispositivo não suporta atestação.
NETWORK_INTEL_UNAVAILABLEnetwork_intelTodasO sinal de inteligência de rede não pôde ser coletado.
FINGERPRINT_DEGRADEDfingerprintWebA impressão digital do navegador não pôde ser calculada.
{
"diagnostics": {
"location": "denied",
"networkIntel": "collected",
"warnings": [{ "code": "LOCATION_PERMISSION_DENIED", "signal": "location" }]
}
}
dica

Use diagnostics para explicar os resultados aos seus usuários ou à equipe de suporte. Por exemplo, peça ao usuário que ative a localização quando location for denied.

Códigos de Status HTTP​

Eles se aplicam aos endpoints que seu backend chama: POST /geolocation/preflight e POST /geolocation/transactions/evaluate.

CódigoSignificado
200Sucesso
400JSON malformado, um campo obrigatório ausente ou um valor de campo inválido
401A requisição não tem o cabeçalho Authorization
403A chave de API é inválida ou está inativa, ou o Guardian não está habilitado para a sua organização
404O caminho não corresponde a nenhum endpoint
409Apenas evaluate: outra requisição com o mesmo event_id ainda está sendo avaliada. Tente novamente após uma breve espera.
5xxErro do servidor. Um 503 é temporário: repita a requisição.

Um 401, e um 403 por chave de API inválida ou inativa, têm este corpo:

{
"error": "<reason>",
"message": "<description>",
"requestId": "<request id>"
}

Todos os outros erros usam o mesmo envelope de um sucesso, com data definido como null:

{
"status_code": 409,
"message": "Conflict: This event_id is already being evaluated; retry shortly",
"data": null
}