Challenges Error Scenarios
FAQ
What are the cases we will receive a 401 in?
If the API key is invalid, or if the access token of the customer against whom auth/charge performed is invalid/expired
What is the action needed to handle this error?
If API Key is invalid, you can create a new API key via Merchant dashboard or contact ZIP
What happens when country_code/phone_number is invalid?
- On /create challenge we return: 400 if Country code is not numeric or great than 3 digits; Mobile number is not numeric or not between 6-12 digits; Country code is empty; Phone number is empty
- On /verify we return: 400, Country code is invalid; The phone number or country code is invalid; Land line number used; Number not provisioned with carrier; Banned country code
What happens when challenge has been expired?
403 invalid_code, this is also used when they are using an OTP that has already been verified.
How many times can we request to resend the challenge?
There is no limit on resends currently.
How many times can OTP can be validated?
Customer can try up to 3 times on the same challenge. If all three attempts fail the phone will become locked.
How do I know when my phone has been temporarily locked?
You will receive a 403 with a phone_locked error type.
Can I attempt to verify a code while in this state?
No, you will receive 403 with a phone_locked error type
Can I resend a code while in this state?
No, you will receive 403 with a phone_locked error type when clicking 'resend' link.
Can I create a new challenge while in this state?
No, you will receive a 403 with a phone_locked error type when you enter the mobile.
How long will a phone remain in a locked state for
A phone will remain locked for 10 mins. The locked time starts from the point at which the lock was triggered (3rd invalid attempt)
API response code details##
Scenario | Status Code | Error Type | Error Description |
|---|---|---|---|
Create Challenge | |||
OTP has been sent | 201 | created | |
Country code is not numeric or great than 3 digits | 400 | invalid_request | The country code provided is in invalid format |
Mobile number is not numeric or not between 6-12 digits | 400 | invalid_request | The phone number provided is in invalid format |
Country code is empty | 400 | invalid_request | Country Code' must not be empty. |
Phone number is empty | 400 | invalid_request | Phone Number' must not be empty |
API key or access token is invalid | 401 | unauthorized | |
Customer mobile or client IP address is in Zip Blacklist | 403 | access_denied | |
Creating a new challenge with mobile number that has already been locked (after 3 failed verify attempts) | 403 | phone_locked | |
Unexpected error occurred | 500 | server_error | |
Polly backoff or timeouted when Blacklist or Twilio is down | 503 | service_unavailable | |
Retry challenge | |||
OTP has been sent | 201 | created | |
Retry with a challenge that's already verified | 403 | invalid_challenge | |
The country code is not a real country code or phone number is incorrect | 400 | invalid_mobile_number | The phone number or country code is invalid |
The country code is not on the list of allowed countries in configuration | 400 | invalid_mobile_number | Country code is banned |
Customer tries to get a OTP resend to their mobile (within 10mins) of their account being locked from failing 3 verification attempts | 403 | phone_locked | |
Unexpected error occurred | 500 | server_error | |
Polly backoff or timeouted when Twilio is down | 503 | service_unavailable | |
Verify OTP | |||
OTP has been verified | 200 | ok | |
Customer without transactable account (token, no account) | 404 | customer_not_found | |
Customer (mobile) does not have any Zip account | 404 | customer_not_found | |
Challenge ID is not in a guid format | 400 | invalid_request | |
Verification code (OTP) is empty | 400 | invalid_request | |
Customer used a incorrect OTP | 403 | invalid_code | Verification code is incorrect |
Customer used a expired OTP (10mins) | 403 | invalid_code | Verification code is incorrect |
Verify with a challenge that's already verified | 403 | invalid_challenge | Challenge has already been verified |
Customer has incorrectly entered the OTP 3 times (on the 4th attempt) | 403 | phone_locked | Customer has entered an incorrect verification code 3 times. They need to wait 10 minutes and get a new verification code. |
Challenge ID does not exist | 404 | not_found | |
Unexpected error occured | 500 | server_error | |
Polly backoff or timeouted when SMS API is down | 503 | service_unavailable | |
Get Challenge status | |||
Challenge status found | 200 | ok | |
Challenge ID is not in a guid format | 400 | validation_error | |
Challenge ID does not exist | 404 | not_found | |
Unexpected error occurred | 500 | server_error | |
Get Application Status | |||
Application Not Started | 404 | application_not_started | |
Application Declined | 404 | application_declined | |
Application Not Eligible | 404 | application_not_eligible | |
Application Not Found | 404 | application_not_found | |
Session Was Used | 403 | session_was_used | |
Session Not Found | 404 | session_not_found | |
Merchant Not Found | 404 | merchant_not_found | |
Request Header Missing | 403 | request_header_missing | |
Customer Not Found | 404 | customer_not_found | |
Get Challenges | |||
Challenge Id Not Found | 404 | challenge_id_not_found | |
InvalidToken | 403 | invalid_token |