Error Codes

SDK Errors (SurtError)

Error	When
notInitialized	verify() called before initialize()
invalidJwt	JWT missing, malformed, or rejected by the backend. Mint a fresh JWT per verify().
networkError	Timeout or no connection
serverError	5xx from backend
attestationFailed	A device integrity check failed — most often a reused JWT. Mint a fresh JWT for each verify().

Native platforms surface these as .notInitialized / .invalidJwt / etc. The React Native bridge surfaces string codes: not_initialized, invalid_jwt, attestation_failed, network_error.

Web SDK errors

The Web SDK (@surtai/guardian-web) uses a separate GuardianError with the codes CRYPTO_UNAVAILABLE, ENCRYPTION_FAILED, and INVALID_OPTIONS. See NPM Package.

Result diagnostics

Every verify() and collect() result includes a diagnostics object so you can see what the SDK observed during the transaction. You read it straight off the result you already get back — it is additive, so existing code is unaffected. The shape is identical on Web, iOS, Android, and React Native.

// 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")

Field	Values	Meaning
location	collected · denied · unavailable · timeout · not_requested	Whether device location was captured, or why not (e.g. the user denied permission).
networkIntel	collected · unavailable · not_requested	Whether the supplementary network-intelligence signal was available for this transaction.
warnings	array of { code, signal, detail? }	Structured, non-fatal notes you can log or surface to support (e.g. LOCATION_PERMISSION_DENIED).

{
  "diagnostics": {
    "location": "denied",
    "networkIntel": "collected",
    "warnings": [{ "code": "LOCATION_PERMISSION_DENIED", "signal": "location" }]
  }
}

tip

Use diagnostics to explain outcomes to your users or support team — for example, prompting the user to enable location when location is denied.

HTTP Status Codes

Code	Meaning
200	Success
400	Malformed JSON or missing required field
401	Invalid or missing Bearer JWT
403	Valid key but missing permission
5xx	Server error