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.
| Error | When |
|---|---|
.notInitialized | verify() 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
| Error | When |
|---|---|
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.
| Platform | error.code | code inside error.message |
|---|---|---|
| iOS | verification_failed from verify(), collect_failed from collect() | not_initialized or network_error |
| Android | verification_failed from verify(), collect_failed from collect(), sdk_error for an unexpected error | Same 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);
}
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")
| Field | Platforms | Values | Meaning |
|---|---|---|---|
location | All | collected · denied · unavailable · timeout · not_requested · error | Whether device location was captured, or why not (for example, the user denied permission). |
attestation | iOS, Android, React Native | collected · failed · unavailable · not_supported · not_requested | Whether 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. |
networkIntel | All | collected · unavailable · not_requested | Whether the supplementary network-intelligence signal was available for this transaction. |
timings | All (iOS from v0.5.3) | object of milliseconds per phase, plus total | Time spent in each phase of the call. |
warnings | All | array 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
| Code | signal | Platforms | Meaning |
|---|---|---|---|
LOCATION_PERMISSION_DENIED | location | All | The user denied the location permission. |
LOCATION_UNAVAILABLE | location | iOS, Web | Location was requested but no position was obtained. |
LOCATION_TIMEOUT | location | Web | The browser did not return a position in time. |
LOCATION_ERROR | location | Web | The browser's Geolocation API failed. |
ATTESTATION_FAILED | attestation | iOS, Android | Attestation was attempted and failed. |
ATTESTATION_UNAVAILABLE | attestation | iOS, Android | Attestation is not available on this device. |
ATTESTATION_NOT_SUPPORTED | attestation | Android | The device does not support attestation. |
NETWORK_INTEL_UNAVAILABLE | network_intel | All | The network-intelligence signal could not be collected. |
FINGERPRINT_DEGRADED | fingerprint | Web | The browser fingerprint could not be computed. |
{
"diagnostics": {
"location": "denied",
"networkIntel": "collected",
"warnings": [{ "code": "LOCATION_PERMISSION_DENIED", "signal": "location" }]
}
}
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.
| Code | Meaning |
|---|---|
200 | Success |
400 | Malformed JSON, a missing required field, or an invalid field value |
401 | The request has no Authorization header |
403 | The API key is invalid or inactive, or Guardian is not enabled for your organization |
404 | The path does not match an endpoint |
409 | Evaluate only: another request with the same event_id is still being evaluated. Retry after a short wait. |
5xx | Server 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
}