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

📘
Error Reporting To FNS
Most customer-facing errors are sent to FNS. For rare errors and 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

🚧
Customer Message Consistency
If you’re building your own UI with a Forage SDK, make sure submitted messages (in the table, below) match what customers see—even if you customize them.

Error scenario	Response code	TPP error description	Customer-facing error message
Invalid PIN	`ebt_error_55`	Invalid PIN or PIN not selected	The PIN you entered is incorrect. Please try again.
PIN Attempts Exceeded	`ebt_error_75`	PIN tries exceeded	Your card was locked after too many incorrect PIN attempts. Please call the number on the back of your EBT card for assistance.
Insufficient Funds	`ebt_error_51`	Insufficient Funds	Insufficient Funds. Remaining balances are SNAP: {}, EBT Cash: {}
Invalid Card/Account	`ebt_error_14`	Invalid card number	Invalid 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/Account	`ebt_error_56` `ebt_error_19` `ebt_error_92`	Card number not found	Invalid card number. Please re-enter your card number and try again.
Inactive Card/Account	`ebt_error_13` `ebt_error_52` `ebt_error_57` `ebt_error_S5`	Inactive EBT Card	This card may be inactive. Please call the number on the back of your EBT card for assistance.
EBT Lost/Stolen card	`ebt_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 Error	`ebt_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 Outage	`ebt_error_03` `ebt_error_05` `ebt_error_39` `ebt_error_96`	General denial - Cannot Process	Online EBT processing is experiencing an outage. Please try again later.
Credit/Debit-only denial	N/A	N/A - Forage not handling credit-only payments	There 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 order	N/A	Merchant Admin system error	There 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 EBT	N/A	Merchant Admin system error	N/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 Purchase	N/A	Merchant Admin system error	N/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_61`	Merchant Admin system error	N/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 order	`ebt_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 order	N/A	Merchant Admin system error	N/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-delivery	N/A	Merchant Admin system error	N/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 Begins	`ebt_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 response	`ebt_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 response	`ebt_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 fulfillment	N/A	Merchant Admin system error	n/a