📘

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 error object 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.

cannot_update_payment

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

Confirm that the payment.status is requires_confirmation or failed before requesting the update, and/or that you passed the correct payment_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.

Call the Create an Order endpoint 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 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

with 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:

{
  errors: [
    {
      httpStatusCode: number,
      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:

{
  "errors": [
    {
      "httpStatusCode": 400,
      "code": "ebt_error_51",
      "message": "Insufficient funds - Insufficient Funds. Remaining balances are SNAP: N/A, EBT Cash: $100.00"
    }
  ]
}

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.

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

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 merchant FNS number.

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.

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.