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:
- 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 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]
Updated 11 months ago