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.
| Fehler | Wann |
|---|---|
.notInitialized | verify() 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
| Fehler | Wann |
|---|---|
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.
| Plattform | error.code | code innerhalb von error.message |
|---|---|---|
| iOS | verification_failed von verify(), collect_failed von collect() | not_initialized oder network_error |
| Android | verification_failed von verify(), collect_failed von collect(), sdk_error bei einem unerwarteten Fehler | Derselbe 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);
}
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")
| Feld | Plattformen | Werte | Bedeutung |
|---|---|---|---|
location | Alle | collected · denied · unavailable · timeout · not_requested · error | Ob der Gerätestandort erfasst wurde, oder warum nicht (zum Beispiel, weil der Nutzer die Berechtigung verweigert hat). |
attestation | iOS, Android, React Native | collected · failed · unavailable · not_supported · not_requested | Ob 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. |
networkIntel | Alle | collected · unavailable · not_requested | Ob das ergänzende Netzwerk-Intelligenz-Signal für diese Transaktion verfügbar war. |
timings | Alle (iOS ab v0.5.3) | Objekt mit Millisekunden pro Phase, plus total | Die in jeder Phase des Aufrufs verbrachte Zeit. |
warnings | Alle | Array 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
| Code | signal | Plattformen | Bedeutung |
|---|---|---|---|
LOCATION_PERMISSION_DENIED | location | Alle | Der Nutzer hat die Standortberechtigung verweigert. |
LOCATION_UNAVAILABLE | location | iOS, Web | Der Standort wurde angefordert, aber es wurde keine Position ermittelt. |
LOCATION_TIMEOUT | location | Web | Der Browser hat nicht rechtzeitig eine Position geliefert. |
LOCATION_ERROR | location | Web | Die Geolocation API des Browsers ist fehlgeschlagen. |
ATTESTATION_FAILED | attestation | iOS, Android | Die Attestierung wurde versucht und ist fehlgeschlagen. |
ATTESTATION_UNAVAILABLE | attestation | iOS, Android | Die Attestierung ist auf diesem Gerät nicht verfügbar. |
ATTESTATION_NOT_SUPPORTED | attestation | Android | Das Gerät unterstützt keine Attestierung. |
NETWORK_INTEL_UNAVAILABLE | network_intel | Alle | Das Netzwerk-Intelligenz-Signal konnte nicht erfasst werden. |
FINGERPRINT_DEGRADED | fingerprint | Web | Der Browser-Fingerabdruck konnte nicht berechnet werden. |
{
"diagnostics": {
"location": "denied",
"networkIntel": "collected",
"warnings": [{ "code": "LOCATION_PERMISSION_DENIED", "signal": "location" }]
}
}
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.
| Code | Bedeutung |
|---|---|
200 | Erfolg |
400 | Fehlerhaftes JSON, ein fehlendes Pflichtfeld oder ein ungültiger Feldwert |
401 | Die Anfrage hat keinen Authorization-Header |
403 | Der API-Schlüssel ist ungültig oder inaktiv, oder Guardian ist für deine Organisation nicht aktiviert |
404 | Der Pfad entspricht keinem Endpoint |
409 | Nur Evaluate: Eine andere Anfrage mit derselben event_id wird noch ausgewertet. Wiederhole die Anfrage nach kurzer Wartezeit. |
5xx | Serverfehler. 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
}