Table of Contents

minLevel	1
maxLevel	7

Error Overview

Flexiti uses conventional HTTP response codes to indicate the success or failure of an API request. In general:

...

Some 4xx errors that could be handled programmatically include an error code that briefly explains the error reported.

HTTP Status Code Summary

HTTP Status Code

s

	Type	Status
200	Success	Everything worked as expected.
401	Unauthorized	An error with the Merchant authentication. Wrong or expired access token.
403	Forbidden	Request is forbidden for the level of access granted.
404	Not Found	The requested resource doesn't exist.
409	Bad Request	The request was unacceptable, often due to missing a required parameter or wrong format.

500

465

Server Errors

Something went wrong on

Blocked	Blocked a request that contained a malicious payload.
466	Blocked	Blocked a request due to an ACL rule.
467	Blocked	Blocked a request because it was Geo-blocked.
500	Server Errors	Something went wrong on the Flexiti side. (These are rare.)

General Input Errors

Input errors will *465/466/467 Status codes can be treated the same way as 403.

General Debugging Notes

If at anytime you receive an error for “general_error”, please email implementation@flexiti.com, as the issue is likely related to your account set-up.

General Input Errors

Input errors will tend to follow this model:

...

Code Block

{
    "url": "/flexiti/pos-api/v2.5/client-id/flexitidemo/customers/828930/verify",
    "message": "Some inputs are wrong!",
    "error": "wrong_input",
    "field_errors": [
        {
            "param": "email",
            "msg": "invalid",
            "value": "johndoe@"
        }
    ]
}

...

Merchant Integration Endpoint Errors

POST /oauth/token

Code	Error	Scenario
400	invalid_client	Wrong or missing client id or client_secret
400	invalid_request	Invalid or missing grant_type parameter
409	invalid_role	The Developer Portal account being used is not provisioned for the API being accessed. Please contact Flexiti Implementation Support.

...

409

wrong_inputs

Invalid parameter

GET /client-id/{

...

clientId}/

...

i18n

Code	Error	Scenario
409

authentication

general_

failure

Wrong Merchant username or password

POST /client-id/{client_id}/apply

Code

Error

Scenario

409

account_type_not_permitted

The merchant is not able to support applications for this account type.

400

general_error

A generic error covering back-end process issues

409

invalid_

error	A generic error covering back-end process issues
409	invalid_role	The Developer Portal account being used is not provisioned for the API being accessed. Please contact Flexiti Implementation Support.
409

application_create_error

There was an error creating the Credit Application due to a 3rd party timeout

409

tos_agreement_required

Terms and Conditions missing or not agreed

409

customer_already_exists

Customer applying already has an account

409

not_verified

For the online channel, the /apply payload contains different personal information than the /init payload using the same token, or incorrect widget_session_id

409

external_location_id_not_found

The external location ID being passed is not registered with Flexiti

...

wrong_inputs

Invalid parameter

Code	Error	Scenario
409	invalid_role	The Developer Portal account being used is not provisioned for the API being accessed. Please contact Flexiti Implementation Support.
409	general_error	A generic error covering back-end process issues
409	wrong_inputs	Invalid parameter

...

Credit Application Endpoint Errors

POST /client-id/{client_id}/

...

apply

Code

Error

Scenario

403

Insufficient scope: authorized scope is insufficient

Scope of the token is not sufficient to access the endpoint

404

not_found

Customer Account not found

400	general_error	A generic error covering back-end process issues
409	invalid_role	The Developer Portal account being used is not provisioned for the API being accessed. Please contact Flexiti Implementation Support.
409

user

application_

not_able_to_purchase

Customer account status different to normal (NNOR)

409

user_not_active

Customer Account is not activated

GET /client-id/{client_id}/customers/search

...

Code

...

Error

...

Scenario

...

403

...

Insufficient scope: authorized scope is insufficient

...

Scope of the token is not sufficient to access the endpoint

...

404

...

not_found

...

Customer Account not found

...

409

...

invalid_role

...

The Developer Portal account being used is not provisioned for the API being accessed. Please contact Flexiti Implementation Support.

...

create_error	There was an error creating the Credit Application due to a 3rd party timeout
409	tos_agreement_required	Terms and Conditions missing or not agreed
409	customer_already_exists	Customer applying already has an account
409	not_verified	For the online channel, the /apply payload contains different personal information than the /init payload using the same token, or incorrect widget_session_id
409	external_location_id_not_found	The external location ID being passed is not registered with Flexiti
409	account_type_not_permitted	The merchant is not able to support applications for this account type.
409	wrong_inputs	Invalid parameter

...

Customer Endpoint Errors

GET /client-id/{client_id}/

...

customers/lookup

Code

Error

Scenario

400

sms_not_valid_phone

Phone number on file invalid/missing

403

Insufficient scope: authorized scope

403	Insufficient scope: authorized scope is insufficient	Scope of the token is not sufficient to access the endpoint
404	not_found	Customer Account not found
409	invalid_role	The Developer Portal account being used is not provisioned for the API being accessed. Please contact Flexiti Implementation Support.
409

merchant_override_is

user_not_able_to_purchase	Customer account status different to normal (NNOR)
409	user_not_

allowed

active

Merchant

Customer Account is not

configured for Merchant Override

activated

409

piw_mismatch

Personal Identification word entered does not match what is on file for the customer

409

secret_answer_mismatch

Security question answer does not match what is on file for the customer

...

merchant_not_support_nonprime_regularpurchase	Customer is non-prime and the Merchant does not accept non-prime or have the appropriate plans.
409	wrong_inputs	Invalid parameter

GET /client-id/{client_id}/

...

customers/search

Code	Error	Scenario
403	Insufficient scope: authorized scope is insufficient	Scope of the token is not sufficient to access the endpoint
404	not_found	Customer Account not found
409	invalid_role	The Developer Portal account being used is not provisioned for the API being accessed. Please contact Flexiti Implementation Support.
409

...

wrong_inputs

Invalid parameter

POST /client-id/{client_id}/

...

account/{account_number}/

...

verify

Code

Error

Scenario

404

400

sms_not_valid_

found

Customer Account not found

409

invalid_role

The

Code

Error

Scenario

403

Insufficient scope: authorized scope is insufficient

Scope of the token is not sufficient to access the endpoint

404

not_found

Customer Account, transaction, not found

409

invalid_role

The Developer Portal account being used is not provisioned for the API being accessed. Please contact Flexiti Implementation Support.

409

generic_error

A generic error covering back-end process issues

409

invalid_transaction_type

wrong value for transaction type in the request

409

wrong_verification_code

Verification code entered is incorrect

409

verification_code_required

Verification code is a required parameter.

409

user_not_active

Customer Account is not activated

409

user_not_able_to_purchase

Customer account status different to normal (NNOR)

409

limit_payment_amount_24

Payments made on the account exceed the $10,000/day limit

409

not_enough_credit

Customer does not have enough open to buy for transaction amount

409

not_verified

For in-store channel the request_id does not match the one passed in the /verify endpoint

409

external_location_id_not_found

The external location ID being passed is not registered with Flexiti

phone	Phone number on file invalid/missing
403	Insufficient scope: authorized scope is insufficient	Scope of the token is not sufficient to access the endpoint
404	not_found	Customer Account or VCC is not found
409	invalid_role	The Developer Portal account being used is not provisioned for the API being accessed. Please contact Flexiti Implementation Support.
409

generic_error

A generic error covering back-end process issues

POST /client-id/{client_id}/transactions

merchant_override_is_not_allowed	Merchant is not configured for Merchant Override
409	regular_purchase_bypass_is_not_allowed	Customer does not qualify for a regular purchase bypass Regular Purchase Bypass is not available in this channel
409	piw_mismatch	Personal Identification word entered does not match what is on file for the customer
409	secret_answer_mismatch	Security question answer does not match what is on file for the customer
409	wrong_inputs	Invalid parameter
409	tries_exceed	The wrong security answer has been attempted on this account more than three times in the last 48 hours.

POST /client-id/{client_id}/accounts/{account_number}/close

Code	Error	Scenario
403	Insufficient scope: authorized scope is insufficient	Scope of the token is not sufficient to access the endpoint
404	not_found	Customer Account not found
409	invalid_role	The Developer Portal account being used is not provisioned for the API being accessed. Please contact Flexiti Implementation Support.

POST /pos-api/client-id/{client_id}/accounts/{account_number}/calculate-interest

Code	Error	Scenario
404	not_found	Customer Account not found
409	invalid_role	The Developer Portal account being used is not provisioned for the API being accessed. Please contact Flexiti Implementation Support.
409	general_error	A generic error covering back-end process issues
409	wrong_inputs	Invalid parameter

...

Transaction Endpoint Errors

POST /client-id/{client

...

_id}/

...

transactions

Code

Error

Scenario

404

not_found

Customer Account not found

404

customer_identity_not_found

the customer didn’t pass through the widget or was not authenticated properly

409

generic_

403	Insufficient scope: authorized scope is insufficient	Scope of the token is not sufficient to access the endpoint
404	not_found	Customer Account, VCC, or transaction not found
409	invalid_role	The Developer Portal account being used is not provisioned for the API being accessed. Please contact Flexiti Implementation Support.
409

credit_exceeded

Amount requested plus interest is greater than the available credit of the customer account.

general_error	A generic error covering back-end process issues
409

auth

invalid_

not

transaction_

allowedMerchant has not been configured for preauthorization

type	wrong value for transaction type in the request
409

plan

wrong_

term

verification_

not_setMerchant has not been configured for the financing option (Plan and Term or Regular Purchase).

code	Verification code entered is incorrect
409

plan

verification_

term

code_

not_available

Plan and Term for prime category for a non-prime customer.

Plan "DP - SAC Interest Accrues" for a QC customer.

Plan "DP - SAC No Payments + No Interest Accrued" for a ROC customer.

required	Verification code is a required parameter.
409	user_not_active	Customer Account is not activated
409	user_not_able_to_purchase	Customer account status different

than

to normal (NNOR)

409

not_

limit_payment_amount_24	Payments made on the account exceed the $10,000/day limit
409	not_enough_credit	Customer does not have enough open to buy for transaction amount
409	not_verified	For in-store channel the request_id does not match the one passed in the /verify endpoint

for online channel the widget_session

409

external_location_id

does not match the one used on the /init endpoint

409

external_location_id_not_found

_not_found

The external location ID being passed is not registered with Flexiti

GET /client-id/{clientId}/authorizations

...

Code

...

Error

...

Scenario

...

403

...

Insufficient scope: authorized scope is insufficient

...

Scope of the token is not sufficient to access the endpoint

...

409

...

invalid_role

...

The Developer Portal account being used is not provisioned for the API being accessed. Please contact Flexiti Implementation Support.

...

409

...

generic_error

...

A generic error covering back-end process issues

...

409

...

date_from_bigger_than_date_to

...

The From date is later than the To date

...

409	account_type_not_permitted	The merchant is not able to support this account type (open/closed loop scenarios)
409	vcc_account_mismatch	The vcc number being passed in the request does not belong to the account number.
409	wrong_inputs	Invalid parameter

POST /client-id/{

...

client-id}/authorization

...

Code
Error
Scenario
403
Insufficient scope: authorized scope is insufficient
Scope of the token is not sufficient to access the endpoint
400
not_found
Authorization ID not found
404
not_found
Customer Account or VCC not found
404
customer_identity_not_found
the customer didn’t pass through the widget or was not authenticated properly
409
invalid_role
The Developer Portal account being used is not provisioned for the API being accessed. Please contact Flexiti Implementation Support.
409
generic
credit_
error
A generic error covering back-end process issues

POST /client-id/{clientId}/authorization/{authorizationId}/release

Code

Error

Scenario

403

Insufficient scope: authorized scope is insufficient

Scope of the token is not sufficient to access the endpoint

404

not_found

Authorization ID not found

409

invalid_role

The Developer Portal account being used is not provisioned for the API being accessed. Please contact Flexiti Implementation Support.

409

generic

exceeded	Amount requested plus interest is greater than the available credit of the customer account.
409	not_permitted	API credentials do not have sufficient permissions to perform an authorization
409	general_error	A generic error covering back-end process issues
409

authorization

auth_not_

ended

allowed

Credit authorization has “closed” status

Merchant has not been configured for preauthorization

409

auth

plan_

amount

term_

exceededRelease amount is greater than the remaining credit authorization amount

409

external_location_id_not_found

The external location

not_set	Merchant has not been configured for the financing option (Plan and Term or Regular Purchase).
409

not_permitted

The employee doesn’t have enough permissions to perform the release

plan_term_not_available	Plan and Term for prime category for a non-prime customer. Plan "DP - SAC Interest Accrues" for a QC customer. Plan "DP - SAC No Payments + No Interest Accrued" for a ROC customer.
409	user_not_able_to_purchase	Customer account status different than normal (NNOR)
409	not_verified	For in-store channel the request_id does not match the one passed in the /verify endpoint for online channel the widget_session_id does not match the one used on the /init endpoint
409	external_location_id_not_found	The external location ID being passed is not registered with Flexiti
409	account_type_not_permitted	The merchant is not able to support this account type (open/closed loop scenarios)
409	vcc_account_mismatch	The vcc number being passed in the request does not belong to the account number.
409	wrong_inputs	Invalid parameter

GET /client-id/{clientId}/authorizations

Code	Error	Scenario
403	Insufficient scope: authorized scope is insufficient	Scope of the token is not sufficient to access the endpoint
409	invalid_role	The Developer Portal account being used is not provisioned for the API being accessed. Please contact Flexiti Implementation Support.
409	general_error	A generic error covering back-end process issues
409	date_from_bigger_than_date_to	The From date is later than the To date
409	wrong_inputs	Invalid parameter

GET /client-id/{clientId}/authorization/{authorizationId}

Code	Error	Scenario
403	Insufficient scope: authorized scope is insufficient	Scope of the token is not sufficient to access the endpoint
400	not_found	Authorization ID not found
409	invalid_role	The Developer Portal account being used is not provisioned for the API being accessed. Please contact Flexiti Implementation Support.
409	general_error	A generic error covering back-end process issues
409	wrong_inputs	Invalid parameter

POST /client-id/{clientId}/authorization/{authorizationId}/release

Code	Error	Scenario
403	Insufficient scope: authorized scope is insufficient	Scope of the token is not sufficient to access the endpoint
404	not_found	Authorization ID not found
409	invalid_role	The Developer Portal account being used is not provisioned for the API being accessed. Please contact Flexiti Implementation Support.
409	generic_error	A generic error covering back-end process issues
409	authorization_ended	Credit authorization has “closed” status
409	auth_amount_exceeded	Release amount is greater than the remaining credit authorization amount.
409	not_permitted	The employee doesn’t have enough permissions to perform the release
409	external_location_id_not_found	The external location ID being passed is not registered with Flexiti
409	wrong_inputs	Invalid parameter

POST /client-id/{clientId}/authorization/{authorizationId}/capture

Code	Error	Scenario
403	Insufficient scope: authorized scope is insufficient	Scope of the token is not sufficient to access the endpoint
404	not_found	Authorization ID not found
409	invalid_role	The Developer Portal account being used is not provisioned for the API being accessed. Please contact Flexiti Implementation Support.
409

generic

general_error	A generic error covering back-end process issues
409	authorization_ended	Credit authorization has “closed” status
409	auth_amount_exceeded	Capture amount is greater than the remaining credit authorization amount.
409	not_permitted	The employee doesn’t have enough permissions to perform the capture, or; Credit authorization has “unauthorized” or “onhold” status
409	external_location_id_not_found	The external location ID being passed is not registered with Flexiti
409	wrong_inputs	Invalid parameter

POST /client-id/{clientId}/authorization/{authorizationId}/capture/{captureId}/return

Code	Error	Scenario
403	Insufficient scope: authorized scope is insufficient	Scope of the token is not sufficient to access the endpoint
404	not_found	Authorization ID

or

, Capture ID, or VCC not found
409	invalid_role	The Developer Portal account being used is not provisioned for the API being accessed. Please contact Flexiti Implementation Support.
409

generic

general_error	A generic error covering back-end process issues
409	capture_amount_exceeded	Return

amount is greater than the remaining captured amount.

409

return_date_exceeded

Capture creation date is more than 100 days old.

409

wrong_transaction_type

The capture is not related to a promotional purchase

409

not_permitted

The employee doesn’t have enough permissions to perform the return

409

external_location_id_not_found

The external location ID being passed is not registered with Flexiti

amount is greater than the remaining captured amount.
409	return_date_exceeded	Capture creation date is more than 100 days old.
409	wrong_transaction_type	The capture is not related to a promotional purchase
409	not_permitted	The employee doesn’t have enough permissions to perform the return
409	external_location_id_not_found	The external location ID being passed is not registered with Flexiti
409	account_type_not_permitted	The merchant is not able to support this account type (open/closed loop scenarios)
409	vcc_account_mismatch	The vcc number being passed in the request does not belong to the account number.
409	wrong_inputs	Invalid parameter

POST /client-id/{client_id}/accounts/{account_number}/refund

Code	Error	Scenario
403	Insufficient scope: authorized scope is insufficient	Scope of the token is not sufficient to access the endpoint
404

not_found

Customer Account

not

found

409

invalid_role

The Developer Portal account being used is not provisioned for the API being accessed. Please contact Flexiti Implementation Support.

409

generic_error

A generic error covering back-end process issues

409

refunds_limit_exceeded_amount

Refund amount exceeds account balance limit.

409

external_location_id_not_found

The external location ID being passed is not registered with Flexiti

GET /client-id/{clientId}/captures

...

Code

...

Error

...

Scenario

...

403

...

Insufficient scope: authorized scope is insufficient

...

Scope of the token is not sufficient to access the endpoint

...

409

...

invalid_role

...

The Developer Portal account being used is not provisioned for the API being accessed. Please contact Flexiti Implementation Support.

...

409

...

generic_error

...

A generic error covering back-end process issues

...

409

...

date_from_bigger_than_date_to

...

The From date is later than the To date

GET /client-id/{clientId}/information

...

Code

...

Error

...

Scenario

...

409

...

generic_error

...

A generic error covering back-end process issues

...

409

...

invalid_role

...

The Developer Portal account being used is not provisioned for the API being accessed. Please contact Flexiti Implementation Support.

...

_found	Customer Account, VCC, or Capture ID not found
409	invalid_role	The Developer Portal account being used is not provisioned for the API being accessed. Please contact Flexiti Implementation Support.
409	general_error	A generic error covering back-end process issues
409	refunds_limit_exceeded_amount	Refund amount exceeds account balance limit.
409	external_location_id_not_found	The external location ID being passed is not registered with Flexiti
409	account_type_not_permitted	The merchant is not able to support this account type (open/closed loop scenarios)
409	vcc_account_mismatch	The vcc number being passed in the request does not belong to the account number.
409	capture_amount_exceeded	Return amount is greater than the remaining captured amount.
409	wrong_inputs	Invalid parameter

GET /client-id/{clientId}/

...

captures

Code	Error	Scenario
403	Insufficient scope: authorized scope is insufficient	Scope of the token is not sufficient to access the endpoint
409	invalid_role	The Developer Portal account being used is not provisioned for the API being accessed. Please contact Flexiti Implementation Support.
409

generic

general_error	A generic error covering back-end process issues
409	date_from_bigger_than_date_to	The From date is later than the To date
409	wrong_inputs	Invalid parameter

404	not_found	Customer Account or VCC not found
404	customer_identity_not_found	the customer didn’t pass through the widget or was not authenticated properly
409	invalid_role	The Developer Portal account being used is not provisioned for the API being accessed. Please contact Flexiti Implementation Support.
409

Page Comparison

Versions Compared

Old Version 53

New Version Current

Key

Error Overview

HTTP Status Code Summary

General Input Errors

General Debugging Notes

General Input Errors

Merchant Integration Endpoint Errors

POST /oauth/token

GET /client-id/{

clientId}/

i18n

POST /client-id/{client_id}/apply

POST /client-id/{clientId}/widget/init

Credit Application Endpoint Errors

POST /client-id/{client_id}/

apply

GET /client-id/{client_id}/customers/search

Customer Endpoint Errors

GET /client-id/{client_id}/

customers/lookup

GET /client-id/{client_id}/

customers/search

POST /client-id/{client_id}/

account/{account_number}/

verify

POST /client-id/{client_id}/transactions

POST /client-id/{client_id}/accounts/{account_number}/close

POST /pos-api/client-id/{client_id}/accounts/{account_number}/calculate-interest

Transaction Endpoint Errors

POST /client-id/{client

_id}/

transactions

GET /client-id/{clientId}/authorizations

POST /client-id/{

client-id}/authorization

POST /client-id/{clientId}/authorization/{authorizationId}/release

GET /client-id/{clientId}/authorizations

GET /client-id/{clientId}/authorization/{authorizationId}

POST /client-id/{clientId}/authorization/{authorizationId}/release

POST /client-id/{clientId}/authorization/{authorizationId}/capture

POST /client-id/{clientId}/authorization/{authorizationId}/capture/{captureId}/return

POST /client-id/{client_id}/accounts/{account_number}/refund

GET /client-id/{clientId}/captures

GET /client-id/{clientId}/information

GET /client-id/{clientId}/

captures