> ## Documentation Index
> Fetch the complete documentation index at: https://otpless.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# API Error Codes

> Reference for the request errors and verification error codes returned by the Create and Status Check APIs.

There are two kinds of errors in the authentication flow:

1. **Request & authentication errors** — returned as an HTTP `4xx` with a top-level `errorCode` when a [Create](/docs/server-initiated-auth/create-api) or [Status Check](/docs/server-initiated-auth/status-check-api) request is rejected (invalid parameters, bad credentials, etc.).
2. **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](/docs/server-initiated-auth/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](/docs/server-initiated-auth/create-api) (`POST /auth/v1/create`) and [Status Check](/docs/server-initiated-auth/status-check-api) (`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](/docs/server-initiated-auth/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. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.