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.
| Erro | Quando |
|---|---|
.notInitialized | verify() 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
| Erro | Quando |
|---|---|
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.
| Plataforma | error.code | code dentro de error.message |
|---|---|---|
| iOS | verification_failed em verify(), collect_failed em collect() | not_initialized ou network_error |
| Android | verification_failed em verify(), collect_failed em collect(), sdk_error para um erro inesperado | Mesmo 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);
}
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")
| Campo | Plataformas | Valores | Significado |
|---|---|---|---|
location | Todas | collected · denied · unavailable · timeout · not_requested · error | Se a localização do dispositivo foi capturada, ou por que não (por exemplo, o usuário negou a permissão). |
attestation | iOS, Android, React Native | collected · failed · unavailable · not_supported · not_requested | Se 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. |
networkIntel | Todas | collected · unavailable · not_requested | Se o sinal complementar de inteligência de rede estava disponível para esta transação. |
timings | Todos (iOS a partir da v0.5.3) | objeto com os milissegundos por fase, mais total | Tempo gasto em cada fase da chamada. |
warnings | Todas | array 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ódigo | signal | Plataformas | Significado |
|---|---|---|---|
LOCATION_PERMISSION_DENIED | location | Todas | O usuário negou a permissão de localização. |
LOCATION_UNAVAILABLE | location | iOS, Web | A localização foi solicitada, mas nenhuma posição foi obtida. |
LOCATION_TIMEOUT | location | Web | O navegador não retornou uma posição a tempo. |
LOCATION_ERROR | location | Web | A API de Geolocalização do navegador falhou. |
ATTESTATION_FAILED | attestation | iOS, Android | A atestação foi tentada e falhou. |
ATTESTATION_UNAVAILABLE | attestation | iOS, Android | A atestação não está disponível neste dispositivo. |
ATTESTATION_NOT_SUPPORTED | attestation | Android | O dispositivo não suporta atestação. |
NETWORK_INTEL_UNAVAILABLE | network_intel | Todas | O sinal de inteligência de rede não pôde ser coletado. |
FINGERPRINT_DEGRADED | fingerprint | Web | A impressão digital do navegador não pôde ser calculada. |
{
"diagnostics": {
"location": "denied",
"networkIntel": "collected",
"warnings": [{ "code": "LOCATION_PERMISSION_DENIED", "signal": "location" }]
}
}
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ódigo | Significado |
|---|---|
200 | Sucesso |
400 | JSON malformado, um campo obrigatório ausente ou um valor de campo inválido |
401 | A requisição não tem o cabeçalho Authorization |
403 | A chave de API é inválida ou está inativa, ou o Guardian não está habilitado para a sua organização |
404 | O caminho não corresponde a nenhum endpoint |
409 | Apenas evaluate: outra requisição com o mesmo event_id ainda está sendo avaliada. Tente novamente após uma breve espera. |
5xx | Erro 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
}