Fehlercodes

SDK-Fehler (SurtError)

Fehler	Wann
notInitialized	verify() vor initialize() aufgerufen
invalidJwt	JWT fehlt, ist fehlerhaft oder wurde vom Backend abgelehnt. Erzeugen Sie pro verify() ein frisches JWT.
networkError	Zeitüberschreitung oder keine Verbindung
serverError	5xx vom Backend
attestationFailed	Eine Geräteintegritätsprüfung ist fehlgeschlagen - meist ein wiederverwendetes JWT. Erzeugen Sie für jeden verify()-Aufruf ein frisches JWT.

Native Plattformen liefern diese als .notInitialized / .invalidJwt usw. Die React-Native-Bridge liefert String-Codes: not_initialized, invalid_jwt, attestation_failed, network_error.

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. Du liest es direkt aus dem Ergebnis, das du ohnehin erhältst - es ist additiv, bestehender Code bleibt also unberührt. Die Struktur ist auf Web, iOS, Android und React Native identisch.

// React Native (verify) — diagnostics ist im Ergebnis enthalten, das du ohnehin erhältst
const result = await GuardianSDK.verify(jwt);
console.log(result.diagnostics?.location);     // z. B. "denied"
console.log(result.diagnostics?.warnings);     // z. B. [{ code: "LOCATION_PERMISSION_DENIED", signal: "location" }]

// Web (collect) — diagnostics liegt neben dem payload
const { payload, diagnostics } = await collect({ collectLocation: true });
console.log(diagnostics.location);

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

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

Feld	Werte	Bedeutung
location	collected · denied · unavailable · timeout · not_requested	Ob der Gerätestandort erfasst wurde - oder warum nicht (z. B. weil der Nutzer die Berechtigung verweigert hat).
networkIntel	collected · unavailable · not_requested	Ob das ergänzende Netzwerk-Intelligenz-Signal für diese Transaktion verfügbar war.
warnings	Array von { code, signal, detail? }	Strukturierte, nicht-fatale Hinweise, die du protokollieren oder dem Support anzeigen kannst (z. B. LOCATION_PERMISSION_DENIED).

{
  "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 - zum Beispiel, um den Nutzer zur Aktivierung des Standorts aufzufordern, wenn location den Wert denied hat.

HTTP-Statuscodes

Code	Bedeutung
200	Erfolg
400	Fehlerhaftes JSON oder fehlendes Pflichtfeld
401	Ungültiges oder fehlendes Bearer-JWT
403	Gültiger Schlüssel, aber fehlende Berechtigung
5xx	Serverfehler