Skip to main content
There are two kinds of errors in the SNA flow:
  1. Request & authentication errors — returned as an HTTP 4xx with a top-level errorCode when a Create or Status Check request is rejected (invalid parameters, bad credentials, etc.).
  2. SNA verification errors — SP-prefixed codes returned by the verification engine. They appear inside auths[].error (with errorCode, message, and a user-friendly description) on the Status Check API when the PRIMARY factor’s status is FAILED.

​
Request & authentication errors

Returned as an HTTP 4xx with a top-level errorCode by the Create (POST /auth/v1/create) and Status Check (GET /auth/v2/status) APIs. Both APIs share these codes; the Applies to column notes any that are specific to one endpoint.
HTTPError codeMessageDescriptionApplies to
4007102Invalid RequestInvalid phone number.Create
4007104Invalid RequestInvalid email.Create
4007106Invalid RequestInvalid phoneNumber or email.Create
4007113Invalid RequestInvalid expiry (must be 60–86400 seconds).Create
4007119Invalid RequestInvalid request Id — the requestId format is incorrect or malformed.Both
4007170Invalid RequestAuth not started yet. Not terminal — if auth was initiated, keep polling.Status Check
4017002Access blockedInvalid clientId / clientSecret credentials.Both
4017012Access blockedMerchant credentials are empty (missing headers).Both
4017019Merchant BlockedYour account has been temporarily blocked. Contact support.Both

​
SNA verification errors

When the PRIMARY factor’s status is FAILED, the Status Check API returns an error object in auths[].error containing the errorCode, a short message, and a user-friendly description. Surface the description to end users; use the errorCode to drive fallback or retry logic.

​
Verification & operator errors

Returned when carrier verification could not complete. Operator/eligibility checks (SP40004–SP40008) are rejected up front; the remaining codes are reported once verification has been attempted.
Error codeMessageDescription
SP40003Verification failedVerification could not be completed. Please try again or contact OTPless support if it continues.
SP40004Country not supportedVerification is not available for this country yet.
SP40005Operator not supportedThis operator is not supported for verification. Please try with a different network.
SP40006Operator not enabledThe operator is not enabled on OTPless.
SP40007Operator mismatchThe network or SIM operator doesn’t match. Please use the same device and number you started with.
SP40008Invalid phone numberThe phone number is invalid. Please enter a valid number and try again.
SP40009HE FailedWe couldn’t verify you with your mobile network. Please try again in a moment.
SP40010Operator server errorThere’s a temporary issue with the operator. Please try again; if it continues, contact OTPless support.
SP40011Verify failedThe phone number doesn’t match the SIM or network. Please use the correct number and try again.
SP40012Session expiredThis verification session has expired. Please start a new verification.
SP40013No session URIDevice match could not be started. Please try again.

​
SDK-reported errors

Reported by the client SDK when the silent network handshake fails on the device (timeouts, connectivity, or operator-URL issues).
Error codeMessageDescription
SP40014Auth TimeoutThe verification timed out. Please try again.
SP40015No Data ConnectionVerification needs a mobile data connection. Please switch off Wi-Fi and try again.
SP40016Operator URL not whitelisted in host appThe host app blocked a cleartext request to the operator URL. Whitelist the URL in the app’s network security config.
SP40017Unable to resolve host URLThe device could not resolve the operator host. Please check the data connection and DNS.
SP40018Duplicate Auth requestAn auth request is already in progress for this session. Please wait or start a new verification.
SP40019Operator - Bad RequestThe operator returned a bad request / bad gateway response.
SP40020Operator URL Connection TimeoutThe connection to the operator URL timed out.
SP40021Failed to connect to host URLThe device could not establish a connection to the operator host URL.
SP40022SSL ErrorAn SSL/TLS error occurred while contacting the operator URL.
SP40023HOST URL ErrorAn unspecified error occurred while contacting the operator host URL.
SP40024Auth CancelledThe verification was cancelled before completion.
SP40025Unknown ErrorsThe verification failed with an unclassified error.

​
System errors

Error codeMessageDescription
SP50001Internal errorSomething went wrong on our end. Please try again. If it continues, contact OTPless support.