Handling Common Errors

On this page you will find information about our common errors, what they mean and how to handle them. This is not an exhaustive list and if you’re looking for more information, please check out the docs tab on our API docs GraphQL playground. If you have any additional questions about our errors, please reach out to our Koalafi team.

Apply Errors

These are the most common errors encountered when using the Apply() mutation:,

Cart Validation: This is an error that happens when an application is approved for a loan/lease but the customer’s cart does not meet the requirements to continue. Cart validation errors will not be returned with the Approval First (Empty Cart) flow.

A Cart Validation Error will look like:

{
     "__typename": "CartValidation",
     "message": "Customer was approved, but their cart total exceeds approval amount",
     "extensions": {
         "validationErrType": "CartTotalExceedsApproval",
         "approvalType": "lease",
         "approvedAmount": "3750"
     }
}

The valdiationErrType will be one of the following

BadCartRequest
CartTotalDoesNotMeetMinimum – the cart total does not meet our required minimum of $200 to use Koalafi for checkout
CartTotalExceedsApproval – the cart total is greater than their approval amount
CartTotalExceedsMaximum – the cart total is greater than our company maximum of $10,000
NonLeaseableItemsTotal – the subtotal of nonleaseable items in their cart is greater than 20% of their total cart total. This is a lease specific error as not all items are able to be leased.
ServiceFeesTooHigh – service fees make up more than 20% of the cart subtotal

Recommended Solution

Use the error extension to retrieve approval type and amount
Show the customer that they have been approved for a loan/lease and the approval amount but that there is an issue with their cart
Using the validationErrType let the customer know how to modify their cart so they can continue to checkout with Koalafi

Lease Restricted: This error is lease specific and is returned when a customer applies for a lease in a state where Koalafi does not offer leases

Recommended Solution

Inform the customer that they are ineligible for a lease due to the state they live in

Soft Decline: There is an error with the application and we are not able to approve their application at this time. The decline field will give more information about why the applicant was declined. If a customer updates the information on their application, then the application can be resubmitted.

{
     "__typename": "SoftDecline",
     "message": "Customer was soft declined",
     "extensions": {
         "declineField": "application was soft declined due to X reason",
         "appId": 123456710,
     }
}

Recommended Solution

Let the customer know there was an issue with their application and encourage them to verify the information they provided on their application
Once their application details have been updated, resubmit their application

Hard Decline: Application has been declined and customer is ineligible for financing with Koalafi

Recommended Solution

Inform the customer that they have been declined for financing

Fatal Error: Something went wrong during the application process. This is most likely due to an error with Koalafi or one of our downstream dependencies

Recommended Solution

Resubmit the application

Update Order Errors

These are the most common errors encountered when using the updateOrderItems mutation. For almost all of these errors, the recommended solution is going to require the customer to update their cart and then have your system attempt to call updateOrderItems again.

**Note to reduce the amount of API calls your system has to make, instead of calling updateOrderItems everytime a customer updates their cart, we suggest only calling updateOrderItems on the checkout screen or right before opening the Koalafi modal.

Cart Validation: This is an error that happens when the customer’s cart does not meet the requirements to checkout with Koalafi.

A Cart Validation Error will look like

{
     "__typename": "CartValidation",
     "message": "Customer was approved, but their cart total exceeds approval amount",
     "extensions": {
         "validationErrType": "CartTotalExceedsApproval",
         "approvalType": "lease",
         "approvedAmount": "3750"
     }
}

The valdiationErrType will be one of the following

CartTotalDoesNotMeetMinimum – the cart total does not meet our required minimum of $300 to use Koalafi for checkout
CartTotalExceedsApproval – the cart total is greater than their approval amount
CartTotalExceedsMaximum – the cart total is greater than our company maximum of $10,000
NonLeaseableItemsTotal – the subtotal of nonleaseable items in their cart is greater than 20% of their total cart total. This is a lease specific error as not all items are able to be leased.
ServiceFeesTooHigh – service fees make up more than 20% of the cart subtotal

Recommended Solution

Ignore the error for now. A customer must get approved for a loan/lease before they can continue to checkout.

BadRequest: This is specifically returned when there is an issue with the underlying state of the application. If we return "message": "unable to update: application already has docs signed" then that means the application approval amount has already been used by the customer in a previous order.

Recommended Solution

In this scenario, we should not allow them to place a new order
Show a message to inform them that they have already used their approval amount and cannot place another order with Koalafi at this time
For Modal Integration - we are working on building out a custom screen to display this message, for now though you'll need to show an error message as suggested in the previous step

Update Bank Account Errors

Errors encountered in the UpdateBankAccount() mutation are fairly rare, however there are certain error scenarios that require extra attention.

Bad Request: This indicates an issue with the request that needs to be resolved.

Recommended Solution

Check the error message that is returned for details on why the request failed and how to address it. Possible causes include
- Attempting to update bank account information for a loan application. This is not currently supported.
Retry UpdateBankAccount

Soft Decline: This indicates that the customer is attempting to use an account from a non-traditional bank. Koalafi does not allow accounts from internet-only banks, and the customer will need to provide an account from a traditional brick and mortar bank to continue the application.

Recommended Solution

Let the customer know Koalafi does not accept the provided bank account.
Give them an opportunity to review and fix the details they entered
Retry UpdateBankAccount

Hard Decline: In this case, Koalafi has evaluated the provided bank account and determined that the application may not continue. Generally this error is returned on the 3rd attempt to fix bad bank account data.

Recommended Solution

If you get a hard decline, we are unable to continue with the financing process. Indicate to the customer that they are unable to continue

Fatal error: Something went wrong while trying to complete the query/mutation. This is most likely due to an error with Koalafi or one of our downstream dependencies.

Recommended Solution

Retry UpdateBankAccount
If the problem persists, let the customer know there is a problem processing their bank account at this time and to please try again later.

Update Debit Info Errors

Errors encountered in the UpdateDebitInfo() mutation are fairly rare, however there are certain error scenarios that require extra attention.

Prepaid Card: We currently do not allow customers to use prepaid cards for the initial lease payment. If they try to use a prepaid card, we return this error

{
    "__typename": "PrepaidCardError",
    "message": "User has used a prepaid card."
}

Recommended Solution

Show a message to the customer letting them know prepaid debit cards are not allowed
Ask them to update their debit card information to one connected to a debit card. We use the following message on our modal, "Please use a debit card connected to a bank account. Prepaid cards are not accepted"
Once they have updated their card information, try the mutation again

Soft Decline: This indications that there is an issue with the debit card information that was passed in.

Recommended Solution

Let the customer know there was a problem with their card
Give them an opportunity to review and fix the details they entered
Retry UpdateDebitInfo

Hard Decline: There was a problem with the debit card information passed in but the customer is not able to attempt to fix the problem. Generally this error is returned on the 3rd attempt to fix bad debit card data.

Recommended Solution

If you get a hard decline, we are unable to continue with the financing process. Indicate to the customer that they are unable to continue

Fatal error: Something went wrong while trying to complete the query/mutation. This is most likely due to an error with Koalafi or one of our downstream dependencies.

Recommended Solution

Retry UpdateDebitInfo
If the problem persists, let the customer know there is a problem processing their card at this time and to please try again later.

General Errors

When possible, we try to reuse error types and in general, these are the most common ones.

Fatal Error: Something went wrong while trying to complete the query/mutation. This is most likely due to an error with Koalafi or one of our downstream dependencies

Recommended Solution

Retry the query/mutation that gave you this error

GraphQL Errors: This is most often caused by requesting an invalid field for a given query or passing the wrong type.

These errors are returned differently than application errors are since they are not part of the expected response object. They will look something like:

{
    "errors": [
        {
            "message": "employment must be defined",
            "path": [
                "apply",
                "employment"
            ]
        },
        {
            "message": "validation Error",
            "path": [
                "apply"
            ]
        }
    ],
    "data": null
}

Occasionally, errors will be returned in conjunction with application errors so we always encourage checking to see if errors is present in the mutation/query response body.

Each error returned in errors is formatted so that message will give you more details about the problem and path will tell you where the problem is.

Recommended Solution

Read the message field for more details on the error
Review your request body and make sure your request matches our schema
If the problem persists, reach out to the Koalafi team via email at [email protected]