Skip to main content
Version: Guardian v0.5.3

Error Codes

SDK Errors (SurtError)​

Each platform reports a failed verify() or collect() in its own way.

iOS​

verify() and collect() fail with a SurtError.

ErrorWhen
.notInitializedverify() or collect() called before GuardianSDK.initialize()
.networkError(Error)Any other failure: no connection, a timeout, or an HTTP error from Surt. The associated error describes the cause.

SurtError also declares .noCustomer, .invalidApiKey, .serverError and .attestationFailed. The SDK does not return them in this version.

Android​

ErrorWhen
IllegalStateException (thrown)GuardianSDK.getInstance() called before GuardianSDK.initialize()
java.io.IOException (in the Result)verify() got an HTTP error from Surt, or the request did not complete. For an HTTP error the message starts with HTTP <status>.
SurtError.NetworkError (in the Result)An unexpected error inside the SDK. underlying holds the cause. collect() reports every failure this way.

verifySuspend() and collectSuspend() return a Kotlin Result. Call .getOrThrow(), or handle onSuccess and onFailure.

On both platforms the SDK sends the verify() request up to 3 times before it returns a failure.

React Native​

verify() and collect() reject with an error that has a code and a message. The message is a JSON string with its own code and message.

Platformerror.codecode inside error.message
iOSverification_failed from verify(), collect_failed from collect()not_initialized or network_error
Androidverification_failed from verify(), collect_failed from collect(), sdk_error for an unexpected errorSame value as 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 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 that describes what the SDK observed during the transaction. Existing code that does not read it is unaffected. React Native returns it from v0.5.2. Some fields exist only on some platforms, as the table shows.

// 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")
FieldPlatformsValuesMeaning
locationAllcollected · denied · unavailable · timeout · not_requested · errorWhether device location was captured, or why not (for example, the user denied permission).
attestationiOS, Android, React Nativecollected · failed · unavailable · not_supported · not_requestedWhether the device produced an attestation (App Attest on iOS, Play Integrity on Android). Android collect() also returns skipped when attestation was not due for this transaction.
networkIntelAllcollected · unavailable · not_requestedWhether the supplementary network-intelligence signal was available for this transaction.
timingsAll (iOS from v0.5.3)object of milliseconds per phase, plus totalTime spent in each phase of the call.
warningsAllarray of { code, signal, detail? }Non-fatal notes you can log or show to support. Always present, possibly empty.

On Android, location is collected when the app holds the location permission, even if the device had no location to report.

Warning codes​

CodesignalPlatformsMeaning
LOCATION_PERMISSION_DENIEDlocationAllThe user denied the location permission.
LOCATION_UNAVAILABLElocationiOS, WebLocation was requested but no position was obtained.
LOCATION_TIMEOUTlocationWebThe browser did not return a position in time.
LOCATION_ERRORlocationWebThe browser's Geolocation API failed.
ATTESTATION_FAILEDattestationiOS, AndroidAttestation was attempted and failed.
ATTESTATION_UNAVAILABLEattestationiOS, AndroidAttestation is not available on this device.
ATTESTATION_NOT_SUPPORTEDattestationAndroidThe device does not support attestation.
NETWORK_INTEL_UNAVAILABLEnetwork_intelAllThe network-intelligence signal could not be collected.
FINGERPRINT_DEGRADEDfingerprintWebThe browser fingerprint could not be computed.
{
"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, prompt the user to enable location when location is denied.

HTTP Status Codes​

These apply to the endpoints your backend calls: POST /geolocation/preflight and POST /geolocation/transactions/evaluate.

CodeMeaning
200Success
400Malformed JSON, a missing required field, or an invalid field value
401The request has no Authorization header
403The API key is invalid or inactive, or Guardian is not enabled for your organization
404The path does not match an endpoint
409Evaluate only: another request with the same event_id is still being evaluated. Retry after a short wait.
5xxServer error. A 503 is temporary: retry the request.

A 401, and a 403 for an invalid or inactive API key, has this body:

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

Every other error uses the same envelope as a success, with data set to null:

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