HomeGuidesReference
Log In
Guides

Document error messages

Learn how to prepare documentation for FNS about customer-facing EBT error messages.

As part of the process to receive FNS approval to accept EBT online, merchants must submit documentation, in the form of a table, about how they communicate errors to customers.

Use the template error table as a starting point to draft the required documentation. The table lists common error scenarios, along with their corresponding descriptions and customer-facing error messages.

Most, but not all, errors and their corresponding customer-facing messages are submitted to FNS. For more obscure errors and developer details like the HTTP status codes, refer to the API Errors reference docs.

FNS doesn’t need to review all possible error messages or HTTP status codes. The template below includes only what is required.

How to use the template error table

Tailor the template to your Forage integration type before submitting it to FNS:

Fully Hosted

If you’re building a Fully Hosted integration, then you can submit the template table as is. The customer-facing messages match the Forage Checkout interface.

Custom

If you’re building a Custom integration, then the template table is either everything that you need to submit or a starting point. The customer-facing messages match the Forage Checkout interface, but if you want to support more error scenarios, then you need to add rows. Refer to the developer documentation for EBT-related error codes to explore more possible errors.

Whatever you submit to FNS must match what your app displays to the customer.

SDKs

If you’re integrating a Forage SDK, then you’re building your own checkout interface. You’re welcome to use the same customer-facing error messages that Forage Checkout does, documented in the table below, or you can write your own. If you want to support more possible errors, then you need to add rows. Refer to the developer documentation for EBT-related error codes to explore more possible errors.

Whatever you submit to FNS must match what your app displays to the customer.

Template error table for FNS documentation

🚧

The customer-facing messages match Forage Checkout exactly.

If you’re integrating a Forage SDK and building your own interface, then the customer-facing message is up to you. You’re welcome to use the messages below or to change them. Just be sure that whatever you submit in the table is the same as what appears to your customers.

Error scenarioResponse codeTPP error descriptionCustomer-facing error message
Invalid PINebt_error_55Invalid PIN or PIN not selectedThe PIN you entered is incorrect. Please try again.
PIN Attempts Exceededebt_error_75PIN tries exceededYour card was locked after too many incorrect PIN attempts. Please call the number on the back of your EBT card for assistance.
Insufficient Fundsebt_error_51Insufficient FundsInsufficient Funds. Remaining balances are SNAP: {}, EBT Cash: {}
Invalid Card/Accountebt_error_14Invalid card numberInvalid card number. Please check and re-enter your card number or contact EBT customer service at the number on the back of your card.
Invalid Card/Accountebt_error_56
ebt_error_19
ebt_error_92
Card number not foundInvalid card number. Please re-enter your card number and try again.
Inactive Card/Accountebt_error_13
ebt_error_52
ebt_error_57
ebt_error_S5
Inactive EBT CardThis card may be inactive. Please call the number on the back of your EBT card for assistance.
EBT Lost/Stolen cardebt_error_41
ebt_error_43
ebt_error_62
Lost Card

Lost/stolen Card
Oops! This card is restricted and can't be used. Please call the number on the back of your EBT card for assistance.
TPP Errorebt_error_76
ebt_error_90
ebt_error_91
Key synchronization error

Processor not logged on

Authorizer not available (time-out)

System malfunction
Oops! Something went wrong. Please try again at a later time.
EBT Network Outageebt_error_03
ebt_error_05
ebt_error_39
ebt_error_96
General denial - Cannot ProcessOnline EBT processing is experiencing an outage. Please try again later.
Credit/Debit-only denialN/AN/A - Forage not handling credit-only paymentsThere was a problem processing your payment. Please try another payment method or contact your payment provider for more information.
Credit/Debit issuer does not respond to final authorization when fulfilling orderN/AMerchant Admin system errorThere was a problem processing your payment.Please try again. If this problem persists, please contact member services.
Refund Errors
Refund Exceeds 90 day limit for EBTN/AMerchant Admin system errorN/A - during refund processing there is no customer facing error message. Merchant admin will prevent refunds from being initiated for transactions more than 90 days old.
Refund Amount Exceeds Original PurchaseN/AMerchant Admin system errorN/A - during refund processing there is no customer facing error message. A refund for more than the original purchase will not be permitted by the merchant’s admin system.
Refund Exceeds Benefit Authorization (EBT Cash)ebt_error_61Merchant Admin system errorN/A - during refund processing there is no customer facing error message. Merchant Admin error, “Oops! The amount requested for refund exceeds benefit authorization. Please try again.”
TPP does not respond to refund request while changing orderebt_error_76
ebt_error_90
ebt_error_91
Processor not logged on

Authorizer not available (time-out)

Transaction destination cannot be found for routing

System malfunction

Key synchronization error
Oops! Something went wrong. Please try again at a later time.
TPP does not respond to refund request while fulfilling orderN/AMerchant Admin system errorN/A - at fulfillment there is no customer facing error message. This will be handled on the merchant/TPP side by repeated attempts to complete the refund or by registering an EBT adjustment request with the Processor. Customer will be notified by phone or email.
TPP does not respond to refund request post-deliveryN/AMerchant Admin system errorN/A - at this stage of the order there is no customer facing error message. This will be handled on the merchant/TPP side by repeated attempts to complete the refund or registering an EBT adjustment request with the Processor. Customer will be notified by phone or email.
Internal Errors or Time-out Errors
Before Order Processing/PIN Entry Beginsebt_error_76
ebt_error_90
ebt_error_91
Processor not logged on

Authorizer not available (time-out)

Transaction destination cannot be found for routing

System malfunction

Key synchronization error
Oops! Something went wrong. Please try again at a later time.
Between PIN entry and EBT Processor responseebt_error_76
ebt_error_90
ebt_error_91
Processor not logged on

Authorizer not available (time-out)

Transaction destination cannot be found for routing

System malfunction

Key synchronization error
Oops! Something went wrong. Please try again at a later time.
Between SNAP approval and Cash responseebt_error_76
ebt_error_90
ebt_error_91
Processor not logged on

Authorizer not available (time-out)

Transaction destination cannot be found for routing

System malfunction

Key synchronization error
Oops! Something went wrong. Please try again at a later time.
During order fulfillmentN/AMerchant Admin system errorn/a