✅
Any failed payment can be retried.
If a transaction fails, then attempt to process the original Payment object again before creating a new one, updating it first if you need to.
You only need to create a new Payment if the old one is canceled.

📘
Find a list of common HTTP status codes at the bottom of the page.

Payments API errors

If something goes wrong during a request, the Forage Payments API responds with an HTTP status code and an errors array that takes the following shape:

[
  {
    "code": "<A short string that describes the error>",
    "message": "<A long string with more context about the code>",
    "source": {
      "resource": "<The type of Forage resource involved in the request>",
      "ref": "<The unique 10 character ref of the specific resource that caused the error, if applicable>"
    }
  }
]

In a more concrete example, if you try to create a session token without valid authentication credentials, here’s how Forage responds:

{
  "path": "/api/session_token/",
  "errors": [
    {
      "code": "invalid_token",
      "message": "Incorrect authentication credentials.",
      "source": {
        "resource": "OAuth_Access_Tokens",
        "ref": ""
      }
    }
  ]
}

The following sections detail the most common code and message pairs — including troubleshooting steps — and all possible resource values returned in Payments API errors.

`code` and `message` pairs

🚧
_order errors are only relevant to Fully Hosted and Custom integrations.

`amount_mismatch`

Payment amount needs to equal to products amount. Payment amount: <payment_amount>, products amount: <products_amount>.

Update the <payment_amount> to match the <products_amount>.

`auth_net_`

Unknown exception from Authorize.net API
Check your Authorize.net implementation, and consult the Authorize.net documentation for support.

`balance_check_only_ebt`

Balance check is not available for non-EBT payment methods

Confirm that the PaymentMethod type is ebt.

`benefit_bin_not_supported`

BIN is currently not supported for benefit.

Reach out to your Forage account manager for support.

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

Payment with ref <payment_ref> is either processing, succeeded, or canceled and therefore cannot be captured.

Confirm that the payment.status is either requires_confirmation or failed before capturing the payment, and/or double check that there isn't a typo in the provided <payment_ref>.

`cannot_change_request`

Two requests were submitted with the same idempotency key, but slightly different request bodies. Please use a new idempotency key if you intended to change the request body

Ensure that the Idemopotency-Key in the request header is unique for each request body.

`cannot_parse_request_body`

Cannot parse the request.

Check the endpoint’s reference documentation and confirm that the request body meets all requirements.

`cannot_refund_after_90_days`

Per federal regulations, refunds to EBT payment methods cannot be processed after 90 days. Payment <payment_ref> succeeded on <payment_success_date>

If this error occurs in development, then confirm that the payment_ref in the request is accurate. If this error occurs during production, then alert the customer or merchant clerk in the front-end user interface that the refund date has passed.

`cannot_refund_payment`

Only Payments in the succeeded state can be refunded, but Payment with ref <payment_ref> is in the state

Confirm that the payment.status value is succeeded.

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

`card_not_reusable`

Payment method <payment_method_ref> is not reusable
Please try the transaction again with a reusable payment method.

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

`ebt_processor_timeout`

Unable to contact EBT processor, please try again shortly.

Try the request again in a few minutes.

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

`expired_session_token`

This token has expired

Send a POST to /session_token/ to generate a new session token.

`fixed_settlement_not_applicable`

The merchant_fixed_settlement and platform_fixed_settlement fields are only applicable to EBT Cash Payments.

Remove the merchant_fixed_settlement and platform_fixed_settlement fields from the request, or update the Payment's funding_type.

`inconsistent_funding_and_payment_method`

Payment was posted with a funding_type of <funding_type>, but the payment_method is <other_funding_type> card.

Update the <funding_type> of the Payment, or use a different payment_method.

`invalid_customer_id`

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

`invalid_expiration_time`

The expiration time requested is past the maximum expiration time of <max_token_expiration_time>

Update the requested token expiration_time to be less than or equal to the maximum possible expiration value.

`invalid_filters`

< filter >: required filter is missing

This error is only returned by Forage reporting endpoints. Check the specific endpoint’s reference documentation to confirm that you’ve provided all of the required parameters, and try the request again.

`invalid_input_data`

Validation errors.

Double check the endpoint’s reference documentation to validate the request body, and scan your implementation for any other errors.

`invalid_merchant_account`

Merchant account FNS number not valid.

Confirm that the FNS number, most often passed in the Merchant-Account header of the request, is accurate.

`invalid_token`

Incorrect authentication credentials.

Confirm that you provided valid authentication credentials. Refer to the specific endpoint’s reference documentation and/or the Forage Authentication guide for help.

`missing_idempotency_key`

You must include a value for the Idempotency-Key header in your requests to this endpoint

Add the Idempotency-Key request header, and/or confirm that the key is valid. Refer to the Idempotency documentation for details.

`missing_merchant_account`

No merchant account was provided.

Add the Merchant-Account request header.

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

`no_payments_on_capture`

Order <order_ref> must have at least one eligible snap or ebt cash payment associated with it. Please add payments with the /api/orders/<order_ref>/payments/endpoint before attempting to capture the order

Confirm that the Order has at least one associated Order Payment of funding type ebt_snap or ebt_cash. Use the Create an Order Payment endpoint to create an Order Payment if needed.

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

`payment_already_captured`

Payment with ref <payment_ref> has already been submitted for capture and therefore cannot be canceled. To reverse this payment, please use a normal refund.

Confirm that the payment_ref passed in the request is correct, or call the Create a Payment Refund endpoint to refund the payment.

`refund_exceeds_order_total`

Requested refund would push the total amount refunded above the original Payment amount. Total amount paid is . 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.

`resource_not_found`

{Resource type} with ref {ref} does not exist for current Merchant with FNS {fns_number}

Confirm that the ref is correct, and/or double check the merchant’s FNS number.

`secure_storage_inaccessible`

Temporarily unable to access data in secure storage. Please try again.

Give the network a few minutes and try the request again.

`settlement_greater_than_amount`

merchant_fixed_settlement + platform_fixed_settlement must be equal to or less than the amount charged. Fixed settlement charged of is greater than amount of

Update the fixed settlement charges to be less than or equal to the amount charged.

`stripe_error`

Unable to process payment with Stripe but generic exception was returned

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

`too_many_requests`

Request was throttled, please try again later.

Refer to request limits documentation for details.

`too_many_tokens`

You have reached the maximum amount of live tokens. You have <number_of_tokens> access tokens.

Use the /o/bulk_revoke/ endpoint to delete extra tokens.

`unknown_server_error`

Unknown exception from EBT network

This is a problem on Forage’s end. Please try the request again.

`unsupported_bin`

You attempted to add a card from Guam or the Virgin Islands, where online EBT processing is not yet supported.

Please use another EBT Card.

`unsupported_payment_platform`

Cards for platform are not currently supported.
Reach out to your Forage account manager for help.

`version_not_found`

<request_method> <request_path> does not exist for API-VERSION:

Confirm that the API-Version header that you passed in the request is accurate. Consult Version history for help.

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

`resource` values

The resource field in the Payments API error response object is a string that represents the involved Forage resource. The value typically corresponds to the requested endpoint. Possible values include:

OAuth_Access_Tokens
Orders
Merchant_Account_Header
Payments
Payment_Methods
Refunds
Reports
Sessions
Idempotency_Key

SDK errors

The Forage SDKs return an error object with the following shape:

{
  httpStatusCode: number,
  code: string,
  message: string
}

public struct ForageError: Error, Codable {
    public let code: String
    public let httpStatusCode: Int
    public let message: String
    public let details: ForageErrorDetails?
}

{
  errors: [
    {
      httpStatusCode: Int,
      code: String,
      message: String,
    }
  ] 
}

In a more concrete example, if a transaction fails due to insufficient funds, then Forage responds with an error that looks like this:

{
  httpStatusCode: 400,
  code: 'ebt_error_51',
  message: 'Insufficient funds - Insufficient Funds. Remaining balances are SNAP: 1.23, EBT Cash: 4.56', 
  details: {
    snapBalance: 1.23,
    cashBalance: 4.56
  }
}

The following sections detail the most common Forage SDK code and message pairs and their troubleshooting steps.

📘
SDK reference documentation

Forage JS

Android

iOS

`code` and `message` pairs

✅
Template customer-facing messages
For corresponding customer-facing messages for each error code, check out the template error table for FNS documentation.

`ebt_error_02`

Bad FNS status for merchant - Cannot Process - Call Customer Service

There’s an issue between the merchant and FNS. Double check that the FNS number in the Merchant-Account header is accurate. If there’s no typo, then reach out to FNS or to your Forage account manager for help.

`ebt_error_03`

Invalid merchant - Cannot Process - Call Customer Service

The merchant’s FNS number is not valid. Double check that the FNS number in the Merchant-Account header is accurate. If there’s no typo, then reach out to FNS or your Forage account manager for help.

`ebt_error_05`

General denial - Cannot Process - Call Customer Service

The EBT network can’t complete the transaction.

`ebt_error_06`

Invalid transaction - Invalid Transaction

The EBT network can’t complete the transaction.

`ebt_error_10`

Partial approval - Approved

in-store only

The EBT network went down during an in-store transaction, but the brick-and-mortar merchant treated the transaction as a success, following the “store and forward” protocol. The EBT network came back online and the merchant attempted to process the transaction, but the EBT Card has insufficient funds. The merchant collects the entire available balance, and the network returns an ebt_error_10. Per FNS regulations, in this rare case the merchant absorbs any outstanding balance as a loss.

`ebt_error_12`

Invalid transaction type - Transaction Not Defined

The EBT network can’t complete the transaction.

`ebt_error_13`

Invalid amount field - Re-enter Transaction

The EBT network can’t process the entered transaction amount.

`ebt_error_14`

Invalid card number - Re-enter Transaction

There’s an issue with the EBT Card number.

`ebt_error_19`

Re-enter transaction - Re-enter Transaction

The EBT network can’t complete the transaction, possibly due to a typo.

`ebt_error_23`

Unacceptable transaction fee - Cannot Process - Call Customer Service

The EBT network can’t complete the transaction, possibly because of merchant errors.

`ebt_error_30`

Format error - Cannot Process - Call Customer Service

The EBT network can’t complete the transaction, likely because of a typo.

`ebt_error_31`

Card has invalid ISO prefix - Cannot Process - Call Customer Service

Forage and the EBT network are having trouble communicating. This error is extremely rare.

`ebt_error_40`

Function not available - Function Unavailable

The EBT network can’t complete the transaction.

`ebt_error_41`

Lost Card - Cannot Process - Call Customer Service

The EBT network associates the card number with a lost card.

`ebt_error_42`

No account - Cannot Process - Call Customer Service

There’s an issue with the EBT Card number.

`ebt_error_43`

Lost/stolen card - Cannot Process - Call Customer Service

The EBT network reports that the EBT Card number belongs to a lost or stolen card.

`ebt_error_51`

Insufficient funds - Insufficient Funds. Remaining balances are SNAP: {number}, EBT Cash: {number}

The EBT and/or SNAP charges exceed the customer’s available EBT Card balance. Update the transaction amounts to match the available balance. For more details, check out the Forage insufficient funds guide.

The complete error object takes the following shape:

{
  httpStatusCode: 400,
  code: 'ebt_error_51',
  message: 'Insufficient funds - Insufficient Funds. Remaining balances are SNAP: 1.23, EBT Cash: 4.56', 
  details: {
    snapBalance: 1.23,
    cashBalance: 4.56
  }
}

case let .failure(error):
  if let forageError = error as? ForageError? {
      let errorDetails = forageError?.details
      if case .insufficientFunds(let snapBalance, let cashBalance)? = errorDetails {
          let snapBalanceText = snapBalance ?? "N/A"
          let cashBalanceText = cashBalance ?? "N/A"
      }
  }

when (response) {
    ...
    is ForageApiResponse.Failure -> {
        val error = response.errors.first()
    
        // handle Insufficient Funds error
        if (error.code == "ebt_error_51") {
            val details = error.details as ForageErrorDetails.EbtError51Details
            val (snapBalance, cashBalance) = details
        }
    }
}

`ebt_error_52`

No account on file - Cannot Process - Call Customer Service

There’s an issue with the EBT Card number.

`ebt_error_54`

Expired card - Expired Card

The EBT network associates the customer’s EBT Card number with an expired card.

`ebt_error_55`

Invalid PIN or PIN not selected - Invalid PIN

The EBT PIN that the customer entered is incorrect.

`ebt_error_56`

Card number not found - Cannot Process - Call Customer Service

The EBT network doesn’t recognize the customer’s EBT Card number.

`ebt_error_57`

Transaction not permitted to cardholder - Transaction Not Defined

The EBT network can’t complete the transaction.

`ebt_error_58`

Invalid transaction - Invalid Transaction

The EBT network can’t complete the transaction.

`ebt_error_59`

Fraud (return card) - Cannot Process - Call Customer Service

The EBT network associates the customer’s EBT Card number with unusual activity.

`ebt_error_61`

Return exceeds benefit authorization - Invalid Transaction

The requested return amount exceeds the issuer’s limit for the customer.

`ebt_error_62`

Restricted card - Cannot Process - Call Customer Service

The EBT network reports an issue with the EBT Card.

`ebt_error_75`

PIN tries exceeded - PIN Tries Exceeded

The customer entered an incorrect PIN four times, so the EBT network canceled the transaction and locked the account for 24 hours.

`ebt_error_76`

Key synchronization error - Cannot Process - Call Customer Service

Forage and FNS are having trouble communicating.

`ebt_error_80`

Voucher expired - Cannot Process - Call Customer Service

in-store only

A voucher is used to manually process SNAP purchases or refunds in the absence of a POS, or if the POS isn’t working. In this error scenario, the EBT network reports that the voucher is expired.

`ebt_error_90`

Processor not logged on - Host Not Available

The EBT network is currently offline.

`ebt_error_91`

Authorizer not available (time-out) - Host Not Available

The EBT network is currently offline.

`ebt_error_92`

Transaction destination cannot be found for routing - Cannot Process

There’s been an issue processing an out-of-state EBT Card number.

`ebt_error_96`

System malfunction - Cannot Process - Call Customer Service

The EBT network can’t complete the transaction.

`ebt_error_A1`

Invalid Voucher ID - Invalid Transaction

in-store only

A voucher is used to manually process SNAP purchases or refunds in the absence of a POS, or if the POS isn’t working. In this error scenario, the EBT network reports that the voucher ID is incorrect.

`ebt_error_A2`

Invalid authorization number (approval code does not match voice approval code) - Invalid Transaction

in-store only

A voucher is used to manually process SNAP purchases or refunds in the absence of a POS, or if the POS isn’t working. In this error scenario, the EBT network reports an issue with the voucher authorization number.

`ebt_error_A3`

Amount greater than original voice authorization - Invalid Transaction

in-store only

A voucher is used to manually process SNAP purchases or refunds in the absence of a POS, or if the POS isn’t working. In this error scenario, the EBT network reports an issue with the authorized transaction amount.

`ebt_error_A4`

Original voice authorization not found for cardholder - Invalid Transaction

in-store only

A voucher is used to manually process SNAP purchases or refunds in the absence of a POS, or if the POS isn’t working. In this error scenario, the EBT network reports an issue authenticating the cardholder identity.

`ebt_error_A5`

FNS number does not match original voice authorization - Invalid Transaction

in-store only

`ebt_error_A6`

Item already cleared - Invalid Transaction

in-store only

A voucher is used to manually process SNAP purchases or refunds in the absence of a POS, or if the POS isn’t working. In this error scenario, the EBT network fails to process a voucher.

`ebt_error_FF`

Invalid HIP Amount - Re-enter Transaction

The Healthy Incentives Program (HIP) benefits amount that the customer entered is not authorized.

`ebt_error_S5`

PIN not selected - PIN Not Selected

A PIN number has not been assigned to this EBT Card.

`ebt_error_S6`

PIN already selected - PIN Already Selected

There’s an issue processing this EBT Card number.

`ebt_error_S7`

Unmatched voucher information - Unmatched Voucher Information

in-store only

A voucher is used to manually process SNAP purchases or refunds in the absence of a POS, or if the POS isn’t working. In this error scenario, the EBT network reports something wrong with the voucher input.

`user_error`

A user submitted incorrect or incomplete information.

Example

{
  httpStatusCode: 400,
  code: 'user_error',
  message:'Invalid EBT Card PIN entered. Please enter your 4-digit PIN.'
}

HTTP status codes

200 - OK

Your request was successful. The Forage API responded with the requested data.

201 - Created

Your request was successful. The Forage API created the requested resource.

204 - No Content

Your request was successful. There is no additional content in the response body or action needed.

400 - Bad Request

Forage rejected the request due to errors in the request body. Refer to the code and message pairs in the response body for troubleshooting details.

401 - Unauthorized

Forage couldn’t validate authentication credentials for the request.

403 - Forbidden

Forage couldn’t validate authentication credentials for the request.

404 - Not Found

The request resource doesn’t exist.

429 - Too Many Requests

Request limit reached.

50X - Internal Server Error

Forage server error independent of the request. The issue may be temporary, so retry the request with the same idempotency key using exponential backoff.

✅Any failed payment can be retried.

📘

Payments API errors

code and message pairs

🚧

amount_mismatch

auth_net_

balance_check_only_ebt

benefit_bin_not_supported

cannot_cancel_order

cannot_capture_order

cannot_capture_payment

cannot_change_request

cannot_parse_request_body

cannot_refund_after_90_days

cannot_refund_payment

cannot_update_order

card_not_reusable

different_ebt_card

duplicate_funding_type

ebt_processor_timeout

exceeds_ebt_cash_total

exceeds_snap_total

expired_session_token

fixed_settlement_not_applicable

inconsistent_funding_and_payment_method

invalid_customer_id

invalid_expiration_time

invalid_filters

invalid_input_data

invalid_merchant_account

invalid_token

missing_idempotency_key

missing_merchant_account

missing_stripe_client_secret

no_payments_on_capture

order_already_refunded

order_is_cancelled

order_not_succeeded

payment_already_captured

refund_exceeds_order_total

resource_not_found

secure_storage_inaccessible

settlement_greater_than_amount

stripe_error

too_many_requests

too_many_tokens

unknown_server_error

unsupported_bin

unsupported_payment_platform

version_not_found

wait_for_batch_refund

wrong_payment_total

resource values

SDK errors

📘SDK reference documentation

code and message pairs

✅Template customer-facing messages

ebt_error_02

ebt_error_03

ebt_error_05

ebt_error_06

ebt_error_10

ebt_error_12

ebt_error_13

ebt_error_14

ebt_error_19

ebt_error_23

ebt_error_30

ebt_error_31

ebt_error_40

ebt_error_41

ebt_error_42

ebt_error_43

ebt_error_51

ebt_error_52

ebt_error_54

ebt_error_55

ebt_error_56

ebt_error_57

✅
Any failed payment can be retried.

`code` and `message` pairs

`amount_mismatch`

`auth_net_`

`balance_check_only_ebt`

`benefit_bin_not_supported`

`cannot_cancel_order`

`cannot_capture_order`

`cannot_capture_payment`

`cannot_change_request`

`cannot_parse_request_body`

`cannot_refund_after_90_days`

`cannot_refund_payment`

`cannot_update_order`

`card_not_reusable`

`different_ebt_card`

`duplicate_funding_type`

`ebt_processor_timeout`

`exceeds_ebt_cash_total`

`exceeds_snap_total`

`expired_session_token`

`fixed_settlement_not_applicable`

`inconsistent_funding_and_payment_method`

`invalid_customer_id`

`invalid_expiration_time`

`invalid_filters`

`invalid_input_data`

`invalid_merchant_account`

`invalid_token`

`missing_idempotency_key`

`missing_merchant_account`

`missing_stripe_client_secret`

`no_payments_on_capture`

`order_already_refunded`

`order_is_cancelled`

`order_not_succeeded`

`payment_already_captured`

`refund_exceeds_order_total`

`resource_not_found`

`secure_storage_inaccessible`

`settlement_greater_than_amount`

`stripe_error`

`too_many_requests`

`too_many_tokens`

`unknown_server_error`

`unsupported_bin`

`unsupported_payment_platform`

`version_not_found`

`wait_for_batch_refund`

`wrong_payment_total`

`resource` values

📘
SDK reference documentation

`code` and `message` pairs

✅
Template customer-facing messages

`ebt_error_02`

`ebt_error_03`

`ebt_error_05`

`ebt_error_06`

`ebt_error_10`

`ebt_error_12`

`ebt_error_13`

`ebt_error_14`

`ebt_error_19`

`ebt_error_23`

`ebt_error_30`

`ebt_error_31`

`ebt_error_40`

`ebt_error_41`

`ebt_error_42`

`ebt_error_43`

`ebt_error_51`

`ebt_error_52`

`ebt_error_54`

`ebt_error_55`

`ebt_error_56`

`ebt_error_57`

`ebt_error_58`

`ebt_error_59`

`ebt_error_61`

`ebt_error_62`