API Error Codes

There are two kinds of errors in the authentication flow:

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.).
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.

HTTP	Error code	Message	Description	Applies to
`400`	`7102`	Invalid Request	Invalid phone number.	Create
`400`	`7104`	Invalid Request	Invalid email.	Create
`400`	`7106`	Invalid Request	Invalid `phoneNumber` or `email`.	Create
`400`	`7113`	Invalid Request	Invalid `expiry` (must be 60–86400 seconds).	Create
`400`	`7119`	Invalid Request	Invalid request Id — the `requestId` format is incorrect or malformed.	Both
`400`	`7176`	Invalid Request	`requestId` is required to start the authentication.	Both
`400`	`7170`	Invalid Request	Auth not started yet. Not terminal — if auth was initiated, keep polling.	Status Check
`401`	`7002`	Access blocked	Invalid `clientId` / `clientSecret` credentials.	Both
`401`	`7012`	Access blocked	Merchant credentials are empty (missing headers).	Both
`401`	`7019`	Merchant Blocked	Your account has been temporarily blocked. Contact support.	Both

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 retry logic.

Error code	Message	Description
`SP40003`	Verification failed	Verification could not be completed. Please try again or contact OTPless support if it continues.
`SP40004`	Country not supported	Verification is not available for this country yet.
`SP40008`	Invalid phone number	The phone number is invalid. Please enter a valid number and try again.
`SP40012`	Session expired	This verification session has expired. Please start a new verification.
`SP40014`	Auth Timeout	The verification timed out. Please try again.
`SP40018`	Duplicate Auth request	An auth request is already in progress for this session. Please wait or start a new verification.
`SP40024`	Auth Cancelled	The verification was cancelled before completion.
`SP40025`	Unknown Errors	The verification failed with an unclassified error.

System errors

Error code	Message	Description
`SP50001`	Internal error	Something went wrong on our end. Please try again. If it continues, contact OTPless support.

​Request & authentication errors

​Verification errors

​System errors

Request & authentication errors

Verification errors

System errors