Zum Hauptinhalt springen
Version: Guardian v0.5.3

Fehlercodes

SDK-Fehler (SurtError)​

Jede Plattform meldet ein fehlgeschlagenes verify() oder collect() auf ihre eigene Weise.

iOS​

verify() und collect() schlagen mit einem SurtError fehl.

FehlerWann
.notInitializedverify() oder collect() vor GuardianSDK.initialize() aufgerufen
.networkError(Error)Jeder andere Fehlschlag: keine Verbindung, eine Zeitüberschreitung oder ein HTTP-Fehler von Surt. Der zugehörige Fehler beschreibt die Ursache.

SurtError deklariert außerdem .noCustomer, .invalidApiKey, .serverError und .attestationFailed. Das SDK gibt sie in dieser Version nicht zurück.

Android​

FehlerWann
IllegalStateException (geworfen)GuardianSDK.getInstance() vor GuardianSDK.initialize() aufgerufen
java.io.IOException (im Result)verify() hat einen HTTP-Fehler von Surt erhalten, oder die Anfrage wurde nicht abgeschlossen. Bei einem HTTP-Fehler beginnt die Meldung mit HTTP <status>.
SurtError.NetworkError (im Result)Ein unerwarteter Fehler innerhalb des SDK. underlying enthält die Ursache. collect() meldet jeden Fehlschlag auf diese Weise.

verifySuspend() und collectSuspend() geben ein Kotlin-Result zurück. Rufe .getOrThrow() auf oder behandle onSuccess und onFailure.

Auf beiden Plattformen sendet das SDK die verify()-Anfrage bis zu 3 Mal, bevor es einen Fehlschlag zurückgibt.

React Native​

verify() und collect() werden mit einem Fehler abgelehnt, der einen code und eine message hat. Die message ist ein JSON-String mit eigenem code und eigener message.

Plattformerror.codecode innerhalb von error.message
iOSverification_failed von verify(), collect_failed von collect()not_initialized oder network_error
Androidverification_failed von verify(), collect_failed von collect(), sdk_error bei einem unerwarteten FehlerDerselbe Wert wie 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);
}
Web-SDK-Fehler

Das Web-SDK (@surtai/guardian-web) verwendet einen separaten GuardianError mit den Codes CRYPTO_UNAVAILABLE, ENCRYPTION_FAILED und INVALID_OPTIONS. Siehe NPM-Paket.

Ergebnis-Diagnose​

Jedes verify()- und collect()-Ergebnis enthält ein diagnostics-Objekt, das beschreibt, was das SDK während der Transaktion beobachtet hat. Bestehender Code, der es nicht liest, bleibt unberührt. React Native gibt es ab v0.5.2 zurück. Einige Felder gibt es nur auf bestimmten Plattformen, wie die Tabelle zeigt.

// 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")
FeldPlattformenWerteBedeutung
locationAllecollected · denied · unavailable · timeout · not_requested · errorOb der Gerätestandort erfasst wurde, oder warum nicht (zum Beispiel, weil der Nutzer die Berechtigung verweigert hat).
attestationiOS, Android, React Nativecollected · failed · unavailable · not_supported · not_requestedOb das Gerät eine Attestierung erzeugt hat (App Attest unter iOS, Play Integrity unter Android). collect() unter Android gibt außerdem skipped zurück, wenn für diese Transaktion keine Attestierung fällig war.
networkIntelAllecollected · unavailable · not_requestedOb das ergänzende Netzwerk-Intelligenz-Signal für diese Transaktion verfügbar war.
timingsAlle (iOS ab v0.5.3)Objekt mit Millisekunden pro Phase, plus totalDie in jeder Phase des Aufrufs verbrachte Zeit.
warningsAlleArray von { code, signal, detail? }Nicht-fatale Hinweise, die du protokollieren oder dem Support anzeigen kannst. Immer vorhanden, möglicherweise leer.

Unter Android ist location collected, wenn die App die Standortberechtigung hat, auch wenn das Gerät keinen Standort melden konnte.

Warncodes​

CodesignalPlattformenBedeutung
LOCATION_PERMISSION_DENIEDlocationAlleDer Nutzer hat die Standortberechtigung verweigert.
LOCATION_UNAVAILABLElocationiOS, WebDer Standort wurde angefordert, aber es wurde keine Position ermittelt.
LOCATION_TIMEOUTlocationWebDer Browser hat nicht rechtzeitig eine Position geliefert.
LOCATION_ERRORlocationWebDie Geolocation API des Browsers ist fehlgeschlagen.
ATTESTATION_FAILEDattestationiOS, AndroidDie Attestierung wurde versucht und ist fehlgeschlagen.
ATTESTATION_UNAVAILABLEattestationiOS, AndroidDie Attestierung ist auf diesem Gerät nicht verfügbar.
ATTESTATION_NOT_SUPPORTEDattestationAndroidDas Gerät unterstützt keine Attestierung.
NETWORK_INTEL_UNAVAILABLEnetwork_intelAlleDas Netzwerk-Intelligenz-Signal konnte nicht erfasst werden.
FINGERPRINT_DEGRADEDfingerprintWebDer Browser-Fingerabdruck konnte nicht berechnet werden.
{
"diagnostics": {
"location": "denied",
"networkIntel": "collected",
"warnings": [{ "code": "LOCATION_PERMISSION_DENIED", "signal": "location" }]
}
}
tipp

Nutze diagnostics, um Ergebnisse für deine Nutzer oder dein Support-Team zu erklären. Fordere den Nutzer zum Beispiel auf, den Standort zu aktivieren, wenn location den Wert denied hat.

HTTP-Statuscodes​

Diese gelten für die Endpoints, die dein Backend aufruft: POST /geolocation/preflight und POST /geolocation/transactions/evaluate.

CodeBedeutung
200Erfolg
400Fehlerhaftes JSON, ein fehlendes Pflichtfeld oder ein ungültiger Feldwert
401Die Anfrage hat keinen Authorization-Header
403Der API-Schlüssel ist ungültig oder inaktiv, oder Guardian ist für deine Organisation nicht aktiviert
404Der Pfad entspricht keinem Endpoint
409Nur Evaluate: Eine andere Anfrage mit derselben event_id wird noch ausgewertet. Wiederhole die Anfrage nach kurzer Wartezeit.
5xxServerfehler. Ein 503 ist vorübergehend: Wiederhole die Anfrage.

Ein 401 sowie ein 403 wegen eines ungültigen oder inaktiven API-Schlüssels haben diesen Body:

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

Jeder andere Fehler verwendet denselben Umschlag wie ein Erfolg, wobei data auf null gesetzt ist:

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