Skip to main content

Error Responses

All error responses have HTTP status code 4xx or 5xx. The response body contains errors field. The errors field contains an array of errors:

Error response example
{
  "errors": [
    {
      "id": "5d094f10-8caf-11ed-83bd-2bcc14ba6c4e",
      "status": 400,
      "code": "INSUFFICIENT_INVENTORY",
      "title": "Not enough inventory",
      "detail": {
        "productId": "clbj0i7w4041d01z60hv53mcm",
        "variantId": "13833901"
      }
    }
  ]
}

We will return multiple errors if multiple errors are encountered. However, most of the time, only one error will be returned.

Payment-related errors will also depend on the paymentMethod provided.

info

Please reach out to Bonsai if you receive any error not listed within this document.

Generic Errors​

INSUFFICIENT_INVENTORY​

CodeReasonNext step
INSUFFICIENT_INVENTORYInsufficient inventory for the requested quantityRequest that the customer changes quantity

Example​

{
  "id": "123e4567-e89b-12d3-a456-426655440000",
  "status": 400,
  "code": "INSUFFICIENT_INVENTORY",
  "title": "Not enough inventory",
  "detail": {
    "productId": "clbj0i7w4041d01z60hv53mcm",
    "variantId": "13833901"
  }
}

OUT_OF_STOCK​

CodeReasonNext step
OUT_OF_STOCKThe product is out of stockRequest that the customer removes product from cart

Example​

{
  "id": "123e4567-e89b-12d3-a456-426655440000",
  "status": 400,
  "code": "OUT_OF_STOCK",
  "title": "The product is out of stock",
  "detail": {
    "public_id": "clbj0i7w4041d01z60hv53mcm",
    "variant_id": "13833901"
  }
}

PAYMENT_REQUIRED​

CodeReasonNext step
PAYMENT_REQUIREDValid payment is requiredRequest that the customer verifies their payment information
info

This error will contain details with more information about what went wrong with the payment. It is safe to show this message to the customer for Payment methods other than external payment.

Example​

{
  "id": "123e4567-e89b-12d3-a456-426655440000",
  "status": 402,
  "code": "PAYMENT_REQUIRED",
  "title": "Payment is required for this order",
  "detail": {
    "message": "Your card was declined."
  }
}

PAYMENT_METHOD_NOT_SUPPORTED​

CodeReasonNext step
PAYMENT_METHOD_NOT_SUPPORTEDPayment method is not supported for the requested productsRequest that the customer chooses a different payment method
info

Bonsai supports 2 payment methods:

  • stripe
  • external payment

Example​

{
  "id": "123e4567-e89b-12d3-a456-426655440000",
  "status": 400,
  "code": "PAYMENT_METHOD_NOT_SUPPORTED",
  "title": "The selected payment method is not supported for this order type",
  "detail": {
    "paymentMethod": "customUnsupportedPayment"
  }
}

PROVINCE_NOT_FOUND​

CodeReasonNext step
PROVINCE_NOT_FOUNDThe province was not foundRequest that the customer verifies their address

Example​

{
  "id": "123e4567-e89b-12d3-a456-426655440000",
  "status": 404,
  "code": "PROVINCE_NOT_FOUND",
  "title": "Could not find delivery province",
  "detail": {
    "province": "non-existent-province"
  }
}

INTERNATIONAL_SHIPPING_ERROR​

CodeReasonNext step
INTERNATIONAL_SHIPPING_ERRORMerchant does not ship to countryCommunicate that the product (publicId/variantId) does not ship to the specified country

Example​

{
  "id": "123e4567-e89b-12d3-a456-426655440000",
  "status": 400,
  "code": "INTERNATIONAL_SHIPPING_ERROR",
  "title": "The merchant does not provide international shipping",
  "detail": [
    {
      "publicId": "clbj0i7w4041d01z60hv53mcm",
      "variantId": "13833901"
    }
  ]
}

PRODUCT_DOES_NOT_EXIST​

CodeReasonNext step
PRODUCT_DOES_NOT_EXISTProduct not foundMark the product as unavailable
info

If this error happens, we suggest verifying the feed ingestion to make sure you are passing the right ids to the Bonsai API as it might also happen to other products.

Example​

{
  "id": "123e4567-e89b-12d3-a456-426655440000",
  "status": 404,
  "code": "PRODUCT_DOES_NOT_EXIST",
  "title": "Product does not exist",
  "detail": {
    "publicId": "clbj0i7w4041d01z60hv53mcm",
    "variantId": "13833901"
  }
}

VARIANT_DOES_NOT_EXIST​

CodeReasonNext step
VARIANT_DOES_NOT_EXISTVariant not foundMark the variant as unavailable
info

If this error happens, we suggest verifying the feed ingestion to make sure you are passing the right ids to the Bonsai API as it might also happen to other products.

Example​

{
  "id": "123e4567-e89b-12d3-a456-426655440000",
  "status": 404,
  "code": "VARIANT_DOES_NOT_EXIST",
  "title": "Variant does not exist",
  "detail": {
    "publicId": "clbj0i7w4041d01z60hv53mcm",
    "variantId": "13833901"
  }
}

PRODUCTS_PRICE_CHANGE​

CodeReasonNext step
PRODUCTS_PRICE_CHANGEThe price of one of the products has changed since the last time it was fetchedRequest that the customer confirms the new price

Example​

{
  "id": "123e4567-e89b-12d3-a456-426655440000",
  "status": 400,
  "code": "PRODUCTS_PRICE_CHANGE",
  "title": "The price of one of the products has changed",
  "detail": {
    "publicId": "clbj0i7w4041d01z60hv53mcm",
    "variantId": "13833901"
  }
}

PRODUCT_UNAVAILABLE​

CodeReasonNext step
PRODUCT_UNAVAILABLEProduct is no longer available for saleMark the product as unavailable
info

Please check this Product feed documentation to learn more on product validation and removal.

Example​

{
  "id": "123e4567-e89b-12d3-a456-426655440000",
  "status": 400,
  "code": "PRODUCT_UNAVAILABLE",
  "title": "The product requested is no longer available",
  "detail": {
    "publicId": "clbj0i7w4041d01z60hv53mcm",
    "variantId": "13833901"
  }
}

INVALID_INPUT​

CodeReasonNext step
INVALID_INPUTRequired fields are missing from the request bodyCheck the format of the requests you're sending to our API

Example​

{
  "id": "123e4567-e89b-12d3-a456-426655440000",
  "status": 400,
  "code": "INVALID_INPUT",
  "title": "Invalid input provided",
  "detail": [
    {
      "message": "\"quantity\" is required",
      "path": [
        "products",
        0,
        "quantity"
      ],
      "type": "any.required",
      "context": {
        "key": "quantity",
        "label": "quantity"
      }
    }
  ]
}

Stripe Payment Method Errors​

STRIPE_ERROR​

CodeReasonNext step
STRIPE_ERRORAn error occurred while communicating with StripeProvide the customer the error message from Stripe (error title)

Example​

{
  "id": "123e4567-e89b-12d3-a456-426655440000",
  "status": 402,
  "code": "STRIPE_ERROR",
  "title": "Your card has insufficient funds.",
  "detail": {
    "stripeToken": "tok_visa_chargeDeclinedInsufficientFunds",
    "customer": {
      "first_name": "Haytham",
      "last_name": "Labrini",
      "email": "qa@shopbonsai.ca"
    }
  }
}
info

If you're using Stripe as payment method, please refer to Stripe docs for possible Stripe error codes.

External Payment Method Errors​

PAYMENT_AMOUNTS_NOT_PROVIDED​

CodeReasonNext step
PAYMENT_AMOUNTS_NOT_PROVIDEDPayment amounts are not provided when using external payment as payment methodPlease provide the amounts when submitting an order with payment method external payment

Example​

{
  "id": "123e4567-e89b-12d3-a456-426655440000",
  "status": 400,
  "code": "PAYMENT_AMOUNTS_NOT_PROVIDED",
  "title": "Payment amounts not provided"
}

ACCOUNT_DOES_NOT_SUPPORT_EXTERNAL_PAYMENT​

CodeReasonNext step
ACCOUNT_DOES_NOT_SUPPORT_EXTERNAL_PAYMENTAccount does not support external paymentPlease reach out to Bonsai to set you up

Example​

{
  "id": "123e4567-e89b-12d3-a456-426655440000",
  "status": 400,
  "code": "ACCOUNT_DOES_NOT_SUPPORT_EXTERNAL_PAYMENT",
  "title": "Account does not support external payment"
}

EXTERNAL_PAYMENT_NOT_IMPLEMENTED_YET​

CodeReasonNext step
EXTERNAL_PAYMENT_NOT_IMPLEMENTED_YETExternal payment type is not implemented for the account yetPlease reach out to Bonsai to set you up

Example​

{
  "id": "123e4567-e89b-12d3-a456-426655440000",
  "status": 402,
  "code": "EXTERNAL_PAYMENT_NOT_IMPLEMENTED_YET",
  "title": "External payment not implemented yet",
  "detail": {
    "token": "<redacted>",
    "externalPaymentType": "api"
  }
}

EXTERNAL_PAYMENT_UNKNOWN_ERROR​

CodeReasonNext step
EXTERNAL_PAYMENT_UNKNOWN_ERRORUnknown error while validating external paymentPlease reach out to Bonsai

Example​

{
  "id": "123e4567-e89b-12d3-a456-426655440000",
  "status": 400,
  "code": "EXTERNAL_PAYMENT_UNKNOWN_ERROR",
  "title": "Unknown error while validating external payment",
}

EXTERNAL_PAYMENT_TOKEN_VALIDATION_FAILED​

CodeReasonNext step
EXTERNAL_PAYMENT_TOKEN_VALIDATION_FAILEDExternal payment token validation failedPlease reach out to Bonsai for more details
info

During setup, you provided us with an endpoint to validate that the provided payment token is valid in your system. If that validation fails, this error will be thrown.

Example​

{
  "id": "123e4567-e89b-12d3-a456-426655440000",
  "status": 402,
  "code": "EXTERNAL_PAYMENT_TOKEN_VALIDATION_FAILED",
  "title": "External payment token validation failed",
}