SDK Error Codes

These are the errors the OTPless Headless SDK reports on the client via its callbacks during the SNA-only flow. They are surfaced in the SDK response — on FAILED (initialization), on a non-200 INITIATE, or on AUTH_TERMINATED.

These are client/SDK errors. For the server-side verification outcome (SP* codes in auths[].error) and gateway request errors, see API Error Codes. The SDK callback is not the source of truth — always confirm the final result with the Status Check API.

Error response structure

{
    "responseType": RESPONSE_TYPE_ENUM,
    "statusCode": INTEGER_STATUS_CODE,
    "response": {
        "errorCode": "ERROR_CODE",
        "errorMessage": "ERROR_MESSAGE"
    }
}

responseType — the callback the error arrived on. Errors are carried only on FAILED, INITIATE, and AUTH_TERMINATED. (SDK_READY and ONETAP are success callbacks and never carry an error.)
statusCode — the HTTP status or an OTPless-curated status code.
errorCode — the OTPless error code (see tables below).
errorMessage — a human-readable description of the error.

AUTH_TERMINATED errors

In the SNA-only flow, a terminal failure is delivered on the AUTH_TERMINATED callback. Common to Android and iOS.

Error code	responseType	Meaning
`7160`	`INITIATE` → `AUTH_TERMINATED`	SNA could not be initiated.
`7161`	`AUTH_TERMINATED`	SNA verification failed.

7160 first surfaces on an INITIATE callback (with the error code) and is then followed by AUTH_TERMINATED; 7161 is delivered directly on AUTH_TERMINATED. In an SNA-only configuration there is no fallback channel — treat both as terminal and rely on the Status Check API result.

SNA verification errors

Outcomes from carrier verification (the silent-auth status). In an SNA-only flow these surface on the INITIATE (with error code) and AUTH_TERMINATED callbacks. Common to both platforms unless noted.

Status code	Error code	Meaning
—	`7122`	Carrier-level IP mismatch.
—	`7128`	Carrier failed to verify the number.
—	`7169`	Duplicate request — verification already completed concurrently.
`9106`	`9106`	Transaction timeout — verification did not complete.

A timeout or exhausted poll ends the flow on AUTH_TERMINATED (7161).

Initialization errors

Reported on the FAILED callback when the SDK cannot initialize. Common to both platforms.

Status code	Error code	Meaning
`5003`	`5003`	SDK initialization failed (all retries exhausted). Re-call `initialize()`.

Request & configuration errors

Surfaced on the INITIATE callback when statusCode != 200. Common to both platforms unless noted.

Status code	Error code	Meaning
`400`	`7101`	Malformed request body.
`400`	`7102`	Invalid mobile number format.
`400`	`7139`	Neither a valid mobile number nor email was provided.
`400`	`7035`	Country code not configured for this merchant.
`400`	`7025`	International verification disabled for this merchant.
`400`	`7001`	Identity is blocked.
`400`	`7005`	Invalid auth state (expired or not found) — the SDK retries automatically.
`400`	`7009`	Request origin does not match the configured login URI.
`404`	`4003`	Channel not active in the dashboard. For SNA-only, ensure SNA is the only enabled channel.
`400`	`7039`	Android only. App’s Android version is deprecated.
`400`	`4000`	iOS only. The request values are incorrect.
`400`	`4001`	iOS only. 2FA is not supported by the headless SDK.
`400`	`5900`	iOS only. The feature requires a newer iOS version.
`401`	`401`	Unauthorized request — check your App ID.

Transaction state errors

Surfaced on the INITIATE callback when the request or token has expired. Call start() again with a fresh requestId.

Status code	Error code	Meaning
`400`	`7304`	Transaction expired.
`400`	`7301`	Token expired or missing.
`400`	`7302`	Auth code expired.

Rate-limit errors

Surfaced on the INITIATE callback with statusCode 429. Common to both platforms.

Error code	Limit dimension
`7020`	General rate limit.
`7022`	Per phone/email identity.
`7023`	Per IP address.
`7024`	Per app.
`7036`	Per auth state.
`7037`	Per auth session.
`7040`	Per country code.
`7041`	Per device ID.
`7417`	Identity — too many requests.

Device precondition errors

SNA requires an active cellular (mobile) data connection. If mobile data is off, the SDK reports this before attempting silent auth. Common to both platforms.

Error code	Meaning
`SP40000`	Data not enabled — the device does not have mobile/SIM data enabled. Prompt the user to enable mobile data and try again.

SP40000 is raised only in the SNA flow — because silent auth depends on a cellular data connection. It does not occur for OTP or any other channel.

Network connectivity errors (iOS)

iOS surfaces granular network errors via the INITIATE response. On Android, a network failure during silent auth is not reported with a distinct code in an SNA-only flow — it ends the flow on AUTH_TERMINATED (7160 / 7161).

Status code	Error code	Meaning
`408`	`9100`	Request timeout.
`503`	`9101`	Network connection was lost.
`503`	`9102`	DNS lookup failed.
`503`	`9103`	Cannot connect to server.
`503`	`9104`	No internet connection.
`503`	`9105`	Secure connection failed (SSL issue).
—	`9110`	OTPless authentication request cancelled.

​Error response structure

​AUTH_TERMINATED errors

​SNA verification errors

​Initialization errors

​Request & configuration errors

​Transaction state errors

​Rate-limit errors

​Device precondition errors

​Network connectivity errors (iOS)

Error response structure

AUTH_TERMINATED errors

SNA verification errors

Initialization errors

Request & configuration errors

Transaction state errors

Rate-limit errors

Device precondition errors

Network connectivity errors (iOS)