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 docsGraphQL 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 $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

  • 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:

  • Modal/Plugin Integration:
    • You can ignore these error messages, our modal handles all the error messaging to the customer and will give them specific actions they can take to fix their cart
  • Direct API:
    • Using the validationErrType, let the customer know how to modify their cart so they can continue to checkout with Koalafi.
    • If a customer has already been approved, use the error extension to retrieve approval type and amount. When handling cart errors, we have found that more details help the customer fix their carts more quickly.
      • Ex. “Your current cart total of $4,500 exceeds your approval amount of $4000. Please remove items from your cart to continue to checkout” vs. “Your cart total is too high”
      • Ex. "You must adjust your cart to be able to checkout with Koalafi, the following items must make up at most 20% ($220.00) of your cart total: 3 Yr. Tire Warranty"
    • Once the customer has adjusted their cart total, try calling updateOrderItems again

CartMinNotMet: This will be returned when the cart total does not meet the required minimum of $300

Recommended Solution:

  • Modal/Plugin Integration:
    • You can ignore these error messages, our modal handles all the error messaging to the customer and will give them specific actions they can take to fix their cart
  • Direct API:
    • Let the customer know they must have at least $300 of merchandise in their cart to checkout with Koalafi
    • Once customer has updated their cart, call updateOrderItems again

NotFound: deprecated We no longer return this error. The order does not have an application associated with it. This is most likely due to the fact that the customer has not finished applying for financing. This API call has updated the items on the order in our DB so when the customer applies for financing the correct cart amount should be applied to the loan/lease.

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 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

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 Validation Errors: This is most often caused by requesting an invalid field for a given query or passing the wrong type.

Recommended Solution

  • Review your request body and make sure your request matches our schema