Reference documentation for Forage Payments API and SDK errors
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
code
and message
pairs
_order
errors are only relevant to Fully Hosted and Custom integrations.
amount_mismatch
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_
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_only_ebt
Balance check is not available for non-EBT payment methods
Confirm that the PaymentMethod
type is ebt
.
benefit_bin_not_supported
benefit_bin_not_supported
BIN is currently not supported for benefit.
Reach out to your Forage account manager for support.
cannot_cancel_order
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
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
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
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_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
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
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
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
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
card_not_reusable
Payment method <payment_method_ref> is not reusable
Please try the transaction again with a reusable payment method.
different_ebt_card
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
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
ebt_processor_timeout
Unable to contact EBT processor, please try again shortly.
Try the request again in a few minutes.
exceeds_ebt_cash_total
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 Payment
s 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
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 Payment
s 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
expired_session_token
This token has expired
Send a POST to /session_token/
to generate a new session token.
fixed_settlement_not_applicable
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
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
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
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
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
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
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
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
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
missing_merchant_account
No merchant account was provided.
Add the Merchant-Account
request header.
missing_stripe_client_secret
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
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
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_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_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_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
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_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
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
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
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
too_many_requests
Request was throttled, please try again later.
Refer to request limits documentation for details.
too_many_tokens
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_server_error
Unknown exception from EBT network
This is a problem on Forage’s end. Please try the request again.
unsupported_bin
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
unsupported_payment_platform
Cards for platform are not currently supported.
Reach out to your Forage account manager for help.
version_not_found
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
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
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
resource
valuesThe 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
code
and message
pairs
code
and message
pairsTemplate customer-facing messages
For corresponding customer-facing messages for each error code, check out the template error table for FNS documentation.
ebt_error_02
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
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
ebt_error_05
General denial - Cannot Process - Call Customer Service
The EBT network can’t complete the transaction.
ebt_error_06
ebt_error_06
Invalid transaction - Invalid Transaction
The EBT network can’t complete the transaction.
ebt_error_10
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
ebt_error_12
Invalid transaction type - Transaction Not Defined
The EBT network can’t complete the transaction.
ebt_error_13
ebt_error_13
Invalid amount field - Re-enter Transaction
The EBT network can’t process the entered transaction amount.
ebt_error_14
ebt_error_14
Invalid card number - Re-enter Transaction
There’s an issue with the EBT Card number.
ebt_error_19
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
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
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
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
ebt_error_40
Function not available - Function Unavailable
The EBT network can’t complete the transaction.
ebt_error_41
ebt_error_41
Lost Card - Cannot Process - Call Customer Service
The EBT network associates the card number with a lost card.
ebt_error_42
ebt_error_42
No account - Cannot Process - Call Customer Service
There’s an issue with the EBT Card number.
ebt_error_43
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
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
ebt_error_52
No account on file - Cannot Process - Call Customer Service
There’s an issue with the EBT Card number.
ebt_error_54
ebt_error_54
Expired card - Expired Card
The EBT network associates the customer’s EBT Card number with an expired card.
ebt_error_55
ebt_error_55
Invalid PIN or PIN not selected - Invalid PIN
The EBT PIN that the customer entered is incorrect.
ebt_error_56
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
ebt_error_57
Transaction not permitted to cardholder - Transaction Not Defined
The EBT network can’t complete the transaction.
ebt_error_58
ebt_error_58
Invalid transaction - Invalid Transaction
The EBT network can’t complete the transaction.
ebt_error_59
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
ebt_error_61
Return exceeds benefit authorization - Invalid Transaction
The requested return amount exceeds the issuer’s limit for the customer.
ebt_error_62
ebt_error_62
Restricted card - Cannot Process - Call Customer Service
The EBT network reports an issue with the EBT Card.
ebt_error_75
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
ebt_error_76
Key synchronization error - Cannot Process - Call Customer Service
Forage and FNS are having trouble communicating.
ebt_error_80
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
ebt_error_90
Processor not logged on - Host Not Available
The EBT network is currently offline.
ebt_error_91
ebt_error_91
Authorizer not available (time-out) - Host Not Available
The EBT network is currently offline.
ebt_error_92
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
ebt_error_96
System malfunction - Cannot Process - Call Customer Service
The EBT network can’t complete the transaction.
ebt_error_A1
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
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
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
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
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
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
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
ebt_error_S5
PIN not selected - PIN Not Selected
A PIN number has not been assigned to this EBT Card.
ebt_error_S6
ebt_error_S6
PIN already selected - PIN Already Selected
There’s an issue processing this EBT Card number.
ebt_error_S7
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.