Errors

Firewall Errors

You will get a network error if your API request is blocked by our firewall.

Generic

HTTP Status Code	`403`

Firewall Error: 418 (Generic)
{
    "error": "Request blocked by firewall",
    "message": "Your request was blocked by our firewall. Please contact us if you believe this was in error."
}

API Key Used Client Side

HTTP Status Code	`418`

Firewall Error: API Key Used Client Side
{
    "error": "Request blocked by firewall",
    "message": "Your request was blocked by our firewall because your API key is being used client side. Verified API keys must only be used server side. Please contact us if you believe this was in error."
}

danger

Never use Verified API keys client side. Only use them server side. Verified API keys allow you to source sensitive data about users, so you must keep them secure. If you use a Verified API key client side, our firewall will block your request, and you'll get this firewall error.

Rate Limit

HTTP Status Code	`429`

Firewall Error: 429 (Rate Limit)
{
    "error": "Request blocked by firewall",
    "message": "Your request was blocked by our firewall due to abnormally high request volume. Please contact us if you believe this was in error."
}

Application Errors

To handle application level errors (returned by Verified API endpoints) for 1-Click Signup, we recommend that you primarily use the response body's data.errorCode, which is a Verified specific error code. See Verified Error Codes below for descriptions of what each code means.

`Error` Type

This definition is also in Error in Types.

Error Type
{
    name: string,
    message: string,
    code: number,
    className: string,
    data: {
        errorCode?: string,
        additionalInputs?: [string], // only for error code OCE011
        inputAttemptsExceeded?: [string], // only for error code OCE019
        identifiers?: {
            [identifierKey: string]: string
        },
        verificationMethod?: {
            [identifierKey: string]: string
        },
        riskSignals?: RiskSignals // only for error codes OCE011, OCE012, OCE013, OCE017, and OCE019
        attemptsRemaining?: integer, // only for OCV error codes
        expiresAt?: integer // only for OCV error codes
    }
}

Property	Type	Format	Description	Example
`name`	`string`	`PascalCase`	Name of the error	`"BadRequest"`
`message`	`string`	`Sentence case`	Message for developer that explains the error	`"Additional information is required to source data for user: birthDate"`
`code`	`number`	3 digits (0-9)	HTTP response status code	`400`
`className`	`string`	`kebab-case`	Class of error	`bad-request`
`data.errorCode`	`enum` See Error Codes for possible values	3 letters and 3 digits (0-9)	Verified error code	`"OCE011"`
`data.additionalInputs`	`[string]`	`camelCase`	Additional inputs to source credentials for user, where multiple values indicates inclusive OR (only included for `OCE011`)	`["birthDate", "ssn4"]`
`data.inputAttemptsExceeded`	`[string]`	`camelCase`	Input(s) for which the attempts limit (3 for each input) has been exceeded (only included for `OCE019`)	`["birthDate", "ssn4"]`
`data.identifiers`	`Object`	`camelCase`	Identifiers includede in the request	`["birthDate", "ssn4"]`
`data.verificationMethod`	`Object`	`camelCase`	Verification method for identifiers includede in the request	`["birthDate", "ssn4"]`
`identifierKey`	`enum` Possible values (see identifiers for details): `phone` `email`	`camelCase`	The type of identifier	`"phone"`
`data.riskSignals`	`RiskSignals`	`Object`	Verified risk signals associated with the 1-Click Signup event (only included for `OCE011`, `OCE012`, `OCE013`, `OCE017`, and `OCE019`)	See `RiskSignals` example
`data.atteptsRemaining`	`integer`	Any number of digits (0-9)	How many verification attempts the user has remaining	`3`
`data.expiresAt`	`integer`	Unix time (milliseconds)	When the verification expires (meaning it can no longer succeed)	`1760053995000`

Example

Error Example
{
    "name": "BadRequest",
    "message": "Additional information is required to source data for user: birthDate, ssn4"
    "code": 400,
    "className": "bad-request",
    "data": {
        "errorCode": "OCE011",
        "additionalInputs": ["birthDate", "ssn4"], // inclusive OR: can pass either or both in next call
        "identifiers": {
            "phone": "+12125550010",
            "email": "richard@piedpiper.com"
        },
        "verificationMethod": {
            "phone": "otp",
            "email": "otp"
        },
        "riskSignals": {
            "overall": {
                "score": 0, // always enabled
                "level": "low", // always enabled
                "recommendation": "allow", // always enabled
                "reasonCodes": [ // add on (ask Verified support to enable)
                    "OCR10021"
                ]
            },
            "phone": { // add on (ask Verified support to enable)
                "carrier": {
                    "id": 0,
                    "name": "Example Carrier"
                }
                "reasonCodes": [
                    "OCR20004",
                    "OCR20005",
                    "OCR20007",
                    "OCR20101"
                ]
            },
            "email": { // add on (ask Verified support to enable)
                "reasonCodes": [
                    "OCR60001",
                    "OCR60002"
                ]
            }
        }
    }
}

Verified Error Codes

An errorCode is a Verified specific error code consisting of 3 letters and 3 numbers:

Codes that begin with ERR are generic.
Codes that begin with SKE are specific to the /client/1-click path, which creates a session key for use in the Verified client SDK. (SKE refers to a Session Key Error.)
Codes that begin with OCE are specific to 1-Click Signup: the /1-click path. (OCE refers to a One Click Error.)

1-Click Health

1-Click Health errors are returned via errors in a 1ClickHealthEntity.

1-Click Verify

Limits

Name	Value	Description
Verification Message Expiration	5 minutes	Time before a verification message (for example containing a verification code) expires
Verification Deletion	24 hours	Time before a `1ClickVerificationEntity` is deleted
Maximum Verification Attempts	3	Maximum number of times a user can attempt to verify, for a given verification flow
Maximum Verification Message Deliveries	3	Maximum number of times a verification message can be delivered, for a given verification flow

Verified Error Codes

An errorCode is a Verified specific error code consisting of 3 letters and 3 numbers:

Codes that begin with ERR are generic.
Codes that begin with OCV are specific to 1-Click Verify: the /1-click/verifications path. (OCV refers to One Click Verify.)

`OCV001`

`message`	`"Invalid or expired verification code"`
`data.attemptsRemaining`	`integer`
`data.expiresAt`	`integer`

When This Is Returned

When the user submitted verification code is invalid or expired.

How to Handle

If there are attempts remaining, resend the verification message. Otherwise, start a new verification flow.

`OCV002`

`message`	`"Maximum verification attempts exceeded"`
`data.attemptsRemaining`	`0`
`data.expiresAt`	`integer`

When This Is Returned

When the user submitted verification code has been tried too many times.

How to Handle

Start a new verification flow.

`OCV003`

`message`	`"Cannot resend code for this verification"`
`data.attemptsRemaining`	`integer`
`data.expiresAt`	`integer`

When This Is Returned

When the verification message cannot be delivered again because the verification status is verified, expired, or failed.

How to Handle

Start a new verification flow.

`OCV004`

`message`	`"Maximum send attempts exceeded"`
`data.attemptsRemaining`	`integer`
`data.expiresAt`	`integer`

When This Is Returned

When the verification message has been delivered too many times.

How to Handle

Start a new verification flow.

`OCV005`

`message`	`"Verification not found"`

When This Is Returned

When the 1-Click Verification has been deleted.

How to Handle

Start a new verification flow.

`OCV006`

`message`	`"Unsupported channel"`

When This Is Returned

When the channel submitted is not supported.

How to Handle

Start a new verification flow with a supported channel.

`OCV007`

`message`	`"Verification expired"`
`data.attemptsRemaining`	`0`
`data.expiresAt`	`integer`

When This Is Returned

When the 1-Click Verification has expired.

How to Handle

Start a new verification flow.

Firewall Errors​

Generic​

API Key Used Client Side​

Rate Limit​

Application Errors​

1-Click Signup​

Error Type​

Example​

Verified Error Codes​

1-Click Health​

1-Click Verify​

Limits​

Verified Error Codes​

OCV001​

OCV002​

OCV003​

OCV004​

OCV005​

OCV006​

OCV007​

Firewall Errors

Generic

API Key Used Client Side

Rate Limit

Application Errors

1-Click Signup

`Error` Type

Example

Verified Error Codes

1-Click Health

1-Click Verify

Limits

Verified Error Codes

`OCV001`

`OCV002`

`OCV003`

`OCV004`

`OCV005`

`OCV006`

`OCV007`