Links
Comment on page

Troubleshooting

We’ve put together some troubleshooting questions to help you quickly identify the root of any issue(s). If you answer "no" to any of the questions below, that’s likely the source of the problem.

API setup

Are you using the correct URL and environment?
Hakuna has two environments available (sandbox and production) and each environment has a unique URL.
Are you using a valid API key and passing it to us in the authorization header?
Hakuna uses API keys to authenticate all requests, and authentication is handled via Bearer Authentication.
Each of our environments requires a unique API key — you can view and manage your keys in the Hakuna merchant console.
If you do not enter a valid API key in your request, you will get a 401 response (unauthorized).
Are you passing us the Hakuna-version header with your request?
For full functionality, we recommend using the current version of our API (v1.2). If you omit the version header, your request will default to the earliest supported version of the API, which could cause some unwanted effects.

Offer creation

Are the request parameters valid?
If request parameters are missing or invalid, you’ll get a 400 response with a invalid_request_parameters error code. To identify the problem, use the validation_errors in the payload.
Are you using the correct Hakuna product category?
If the product category doesn’t exist (i.e., because you’re using a sandbox product category in production or vice versa), you’ll get a 400 response with a product_unsupported error code.
Make sure that you are using the correct Hakuna product categories, and that your products are properly mapped to them. If you haven't received your production product categories yet, please reach out to us.
Are you using the correct price amount?
The price amount must be in cents and rounded to the full cent value. If the price falls outside of the accepted price range for a given product category, you’ll get a 400 response with a product_unsupported error code.
Are you using the correct country?
To be able to create an Offer for a specific country, you need to be approved to sell product protection in that country. If you try to create an Offer for a country that you don't have approval for, you’ll get a 400 response.
Also, make sure that the country code in your Offer requests is a lowercase two-character ISO 3166-1 alpha-2 code (e.g., "nl" for the Netherlands). If you format the country code incorrectly or provide an invalid country code, you’ll also get a 400 response.
Are you using the correct currency?
All product prices need to be in the currency of the country you're creating the Offer for.
Are you using the correct sales channel?
To be able to create an Offer for a sales channel other than e-commerce (e.g. post-purchase), you need to be approved to sell product protection via that sales channel. If you try to create an Offer for a sales channel that you don't have approval for, you’ll get a 400 response.

Order feed

Are the request parameters valid?
If request parameters are missing or invalid, you’ll get a 400 response with a invalid_request_parameters error code. To identify the problem, use the validation_errors in the payload. Note: if you pass us two or more line items without line item ids, you’ll get an error with the message “Order must have unique line items”.
Are the Offers valid?
Offers have expiry dates, and you can’t place an Order with an expired Offer. Check to make sure that the Offer is still valid, and if you haven’t already, introduce logic that allows you to update your Offers as needed.
Are all Order changes evolutionary?
Evolutionary changes, such as placement, cancellation, fulfillment, or refund, reflect the normal evolution of an Order and can be reflected in the Order properties. Any other changes to an Order (e.g., changes to customer data or the quantity of line items) are considered non-evolutionary and are prohibited.
Are the fulfillments and refunds arrays for all Hakuna line items empty?
Since they are virtual products, Hakuna protection plans do not need to be fulfilled or refunded independently. We just need to know when the protected product was delivered or refunded. Please leave the fulfillments and refunds arrays for any Hakuna line items empty.
Is the customer's address in the defined insurance coverage area?
If the customer's address is not within the defined insurance coverage area of the Offer you're placing an Order for, you’ll get a 400 response with an invalid_request_parameters error code. Make sure that you're showing the right Offers in the right locations.
Are you using the correct currency?
All price data needs to be in the same currency, and the currency of the price data provided must match the currency of the protection plan that the Order is being placed for.
Is the sales channel consistent across the Offer, the plan and the Order?
If the Offer and the plan within an Order do not have the same sales channel as the Order itself, you’ll get a 400 response with an invalid_request_parameters error code.
Also, keep in mind that the Order feed does not support post-purchase.

Order management

Are the request parameters valid?
If request parameters are missing or invalid, you’ll get a 400 response with a invalid_request_parameters error code. To identify the problem, use the validation_errors in the payload.
Are the Offers valid?
Offers have expiry dates, and you can’t place an Order with an expired Offer. Check to make sure that the Offer is still valid, and if you haven’t already, introduce logic that allows you to update your Offers as needed.
Is the customer's address in the defined insurance coverage area?
If the customer's address is not within the defined insurance coverage area of the Offer you're placing an Order for, you’ll get a 400 response with an invalid_request_parameters error code. Make sure that you're showing the right Offers in the right locations.
Are you using the correct currency?
All price data needs to be in the same currency, and the currency of the price data provided must match the currency of the protection plan that the Order is being placed for.
Is the sales channel consistent across the Offer, the plan and the Order?
If the Offer and the plan within an Order do not have the same sales channel as the Order itself, you’ll get a 400 response with an invalid_request_parameters error code.
Also, keep in mind that e-commerce is the default sales channel.
Do your Order changes conform to our logic?
Here’s an overview of the most important rules:
  • You have to place an Order before you can cancel it or fulfill the line items within it
  • Once you cancel an Order, you can no longer fulfill the line items within it
  • Once you fulfill any line items in an Order, you can no longer cancel it
  • You can only refund line items that have already been fulfilled