HomeGuidesReference
Log In
Reference

Fully Hosted

Error documentation for Fully Hosted integrations

With a Forage Fully Hosted integration, an EBT cardholder interacts with a prebuilt Forage UI that’s embedded in your website and app. In the case of an error, the UI responds with a message to the cardholder that details troubleshooting steps.

This reference documents error scenarios and their corresponding Forage UI messages. It also lists the Payments API errors that developers might encounter when building a Fully Hosted integration.

Cardholder-facing error messages

Error scenarioForage UI message
The cardholder attempted to overpay with SNAP.The SNAP total that you entered exceeds the SNAP-eligible total of the order. Please update the SNAP amount and try again.
The cardholder tried to apply EBT Cash to their purchase, but the US State that issued their benefit card does not support online EBT Cash transactions.Unfortunately, online EBT Cash is not supported for the US state that issued your card. Please remove the EBT Cash contribution and try again.
Either the cardholder attempted to pay with an EBT Card issued from an entity that does not support online EBT transactions (like Guam, or the Virgin Islands), or they attempted to pay with a different unsupported payment method.EBT Cards from your state cannot be used online. We apologize for the inconvenience!
The card number could not be processed.

This could be because the number is invalid, the EBT network can’t find an associated account, the card is marked as restricted, or for some other reason.
Invalid card number. Please check and re-enter your card
The EBT Card is inactive.This EBT Card may be inactive. Please call the number on the back of the card for assistance.
For some unknown reason, the EBT Card has been disabled or could not be charged.This EBT Card could not be charged. Please contact customer service at the phone number on the back of the card for help.
The cardholder hasn’t yet activated their EBT Card.This EBT Card hasn't been activated. Please contact customer service at the phone number on the back of the card.
The EBT Card is restricted.Oops! This EBT Card is restricted and can't be used. Please call the phone number on the back of the card for help.
The EBT Card has insufficient funds to complete a purchase.Insufficient Funds. Remaining balances are SNAP: {snap_balance}, EBT Cash: {ebt_cash_balance}.
The EBT Card is expired.This EBT Card is expired. Please contact customer service at the phone number listed on the back of the card for help.
The cardholder entered an invalid PIN.The PIN you entered is incorrect. Please try again.
The cardholder entered an invalid PIN so many times that the EBT network locked their card.

The number of allowed incorrect attempts varies by US State.
This EBT Card has been locked after too many PIN attempts. Please contact customer service at the phone number listed on the back of the card for help.
Something has gone wrong with the EBT processing network.Online EBT processing is experiencing an outage. Please try again later.
There’s a key synchronization issue. This is typically a very brief error that can be resolved with a retry.Oops! Something went wrong. Please try again at a later time.
The EBT network suspected fraudulent activity and blocked the transaction.Something went wrong. Please contact EBT customer service at the number on the back of your EBT card.
The cardholder attempted to cancel an order that can no longer be canceled.Oops! Something went wrong and we couldn't cancel the order. Please try again.
For some reason, the order could not be captured.Oops! Something went wrong and we couldn't process your order. Please try again.
Forage is unable to connect to the EBT processor for the US state that issued the customer’s card.Oops! We cannot connect to your state's EBT processor. Try again later.
The cardholder’s checkout session expired.We're sorry, but something went wrong. Please try again later.
There was an issue processing the cardholder’s credit or debit card.We're sorry, but your credit or debit card could not be processed. If this problem persists, please contact merchant support.
There was an issue processing the cardholder’s credit card, and they should try the transaction again.There was a problem processing your credit card. Please try again.

Developer-facing Payments API Fully Hosted endpoint errors

📘

Refer to the general Errors reference for more about the shape of Forage errors, a list of error codes that all endpoints can return, and codes returned by the endpoints common to all integration types.

A Payments API error response object includes a code and message pair that describes the failure, as in the following example:

{
  "path": "/api/orders/{order_ref}/",
  "errors": [
    {
      "code": "cannot_update_order",
      "message": "Order <order_ref> has been canceled and therefore cannot be updated. Please create a new order to continue.",
      "source": {
        "resource": "Orders",
        "ref": "{order_ref}"
      }
    }
  ]
}

In addition to the errors that all endpoints can return, Fully Hosted-specific endpoints can return a set of specific code and message pairs. These are all listed below, in addition to their corresponding troubleshooting steps.

cannot_cancel_order

Order {order_ref} is in the {order_status} state and therefore cannot be canceled. Only orders in the draft or failed states can be cancelled.

Confirm that order.status is in a draft or failed state, and/or that you passed the correct order_ref .

cannot_capture_order

Order {order_ref} is in the {order_status} state and therefore cannot be captured. Only orders in the draft or failed states can be submitted for capture.

Confirm that the order.status is in a draft or failed state, and/or that you passed the correct order_ref.

cannot_update_order

Order {order_ref} has been canceled and therefore cannot be updated. Please create a new order to continue.

Confirm that the order.status is in any state other than canceled, and/or that you passed the correct order_ref.

different_ebt_card

Order {order_ref} already has EBT Payment {payment_ref} with payment_method {payment_method_ref}. Your request included payment_method {other_payment_method_ref}. You must use the same EBT payment_method for all EBT Payments on an Order

Confirm that you're using the same payment method for all EBT order payments.

duplicate_funding_type

Order {order_ref} already has payment {payment_ref} with funding_type {funding_type}. Please modify the existing payment object instead of adding new payments with the same funding_type

Confirm that the payment_method passed in the body of the request is accurate, and/or call the Update an order payment endpoint to modify the existing Order Payment.

exceeds_ebt_cash_total

Order {order_ref} has EBT-Cash payments {payment_ref}s with amounts that exceed the Cash eligible total of {ebt_cash_total}. Please update the Order Payments before capturing the order

Confirm that the combined amount of all Order Payments with funding type ebt_cash is less than or equal to the Order's ebt_cash_total. Call the Update an order payment endpoint if you need to modify an existing Order Payment.

exceeds_snap_total

Order {order_ref} has EBT-SNAP payments {payment_ref}s with amounts that exceed the SNAP eligible total of {ebt_cash_total}. Please update the Order Payments before capturing the order

Confirm that the combined amount for all Order Payments with funding type ebt_snap is less than or equal to the Order's snap_total. Call the Update an order payment endpoint if you need to to modify an existing Order Payment.

generic_cc_failure

A generic failure response on the credit card payment was requested through a special toggle on the Forage frontend.

No action required.

invalid_customer_id

Your credit card processor can't identify a customer with the provided customer ID. Double check the ID and your implementation.

missing_stripe_client_secret

Stripe client secret from Payment Intent creation was never supplied to Forage Payment object or the client secret is malformed

Double check that your Stripe integration is set up correctly. Refer to the Stripe error documentation for details.

order_already_refunded

Payments associated with order {order_ref} have already been fully refunded.

Confirm that you passed the correct order_ref.

order_is_cancelled

Order {order_ref} has been cancelled and therefore cannot have new payments added. Please create a new order to continue.

Create a new Session to create a new Order.

order_not_succeeded

Order with ref {order_ref} has not completed successfully and therefore cannot be refunded. Current order status is {order_status}

Confirm that order.status is succeeded before attempting a refund, and/or confirm that the provided order_ref is accurate.

refund_exceeds_order_total

Requested refund would push the total amount refunded above the original Payment amount. Total amount paid is {amount}. Existing total of refunds is {refund_amount}

Confirm that the requested refund amount is less than or equal to the original payment amount and try the refund again.

stripe_error

Unable to process payment with Stripe but generic exception was returned

Refer to the Stripe error documentation for more information. Only the PaymentIntentPaymentMethodCustomer , and Refunds errors apply to Forage integrations.

unknown_braintree_error

Unable to process payment with Braintree but generic exception was returned

Refer to the Braintree documentation for more information.

unknown_stripe_error

Unable to process payment with Stripe but generic exception was returned

Refer to the Stripe error documentation for more information.

wait_for_batch_refund

Order with ref {order_ref} has other active refunds and therefore cannot be batch refunded. Existing refunds in processing state are {refund_refs}

Confirm that the status of all associated Order Refunds is succeeded, and/or wait a few minutes and try the Order Refund again.

wrong_payment_total

Order {order_ref} has payments {payment_ref}s with amounts that do not sum up to the order total of {order_total}. Please update the Payments before capturing the order

Confirm that the sum of the amount values of Order Payment s associated with the Order matches the sum of the Order's ebt_cash_total and snap_total values.