HomeGuidesReference
Log In

SDK

Errors documentation for SDK integration-related endpoints

An SDK integration calls both Payments API endpoints and SDK methods.

This guide lists all the code and message pairs that are relevant to SDK integrations. It begins with a list of errors that only endpoints return, and continues with the pairs that both endpoints and SDK methods return.

Endpoint errors

A Payments API error response object includes a code and message pair that describes the failure, as in the following example:

{
  "path": "/api/payments/{payment_ref}/refunds/",
  "errors": [
    {
      "code": "cannot_refund_after_90_days",
      "message": "Per federal regulations, refunds to EBT payment methods cannot be processed after 90 days. Payment <payment_ref> succeeded on <payment_success_date>",
      "source": {
        "resource": "Payments",
        "ref": "{payment_ref}"
      }
    }
  ]
}

In addition to the errors that all endpoints can return, SDK integration-related endpoints can return a set of specific code and message pairs. These are all listed below, in addition to their corresponding troubleshooting steps.

📘

Refer to the general Errors reference for more about the shape of Forage errors, a list of error codes that all endpoints can return, and codes returned by the endpoints common to all integration types.

amount_mismatch

Payment amount needs to equal to products amount. Payment amount: {payment_amount}, products amount: {products_amount}.

Prompt the cardholder to update the {payment_amount} to match the {products_amount}.

✅

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.

cannot_capture_payment

One of several possible messages might accompany this code.

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

or

Amount value is null. Payment with ref {payment.ref} with funding_type {payment.funding_type} cannot be captured with a null amount value

or

'is_delivery' value is null. Payment with ref {payment.ref} requires a valid 'is_delivery' value for capture.

Depending on the message, confirm that the payment.status, payment.funding_type, or payment.is_delivery value is correct before capturing the payment, and/or double check that there isn't a typo in the provided payment_ref. If all else fails, create a new Payment for the cardholder and prompt them to retry.

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

One of several messages might accompany this code.

Only Payments in the succeeded state can be refunded, but Payment with ref {payment_ref} is in the state {payment_state}

or

Only Payments with a non-null amount can be refunded, but Payment with ref {} has no amount provided.

or

Refund for payment ref {} misses a pin. Please use the SDK to collect pin first.

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_void

Payment with ref {payment_ref} cannot be voided because it is in the {payment_state} state. Only payments in the succeeded state can be voided

Confirm that the payment_ref and/or refund_ref in the request is accurate and that its status value is succeeded.

card_not_reusable

Payment method {payment_method_ref} is not reusable

Prompt the cardholder to try the transaction again with a reusable payment method.

different_ebt_card

SNAP payment method ref {payment_method_ref} is different from EBT Cash payment method ref {payment_method_ref}. You must use the same EBT payment_method for all EBT Payments on an Order

Prompt the cardholder to reenter their EBT Card details.

ebt_cash_not_supported

Ebt cash payment cannot be captured in {US State}

Prompt the cardholder to update their payment method and try again.

Endpoint and SDK method errors

The following code and message pairs can be returned by both SDK integration-related endpoints and SDK methods.

ebt_error_* codes

✅

In the case of an ebt_error_* code , the response always includes the original resource, in addition to the errors field.

For example, an ebt_error_43 returned in the case of a lost or stolen card takes the following shape: 

{
    "ref": "55ca7f3c35",
    "merchant": "9000034",
    "funding_type": "ebt_snap",
    "amount": "1.00",
    "description": "Testing app payments (SNAP Purchase)",
    "metadata": {},
    "payment_method": "6sc7bcd229",
    "delivery_address": null,
    "is_delivery": false,
    "created": "2024-05-07T11:04:58.967491-07:00",
    "updated": "2024-05-07T11:05:15.432620-07:00",
    "status": "failed",
    "last_processing_error": null,
    "success_date": null,
    "receipt": {
        "ref_number": "55ca7f3c35",
        "is_voided": false,
        "snap_amount": "1.00",
        "ebt_cash_amount": "0.00",
        "cash_back_amount": "0.00",
        "other_amount": "0.00",
        "sales_tax_applied": "0.00",
        "balance": null,
        "last_4": "4443",
        "message": "Lost/stolen card - Cannot Process - Call Customer Service",
        "transaction_type": "Payment",
        "created": "2024-05-07T11:05:15.427552-07:00",
        "sequence_number": "PA022ba7"
    },
    "expires_at": "2024-05-07T18:35:15.432620Z",
    "pos_terminal": {
        "terminal_id": "0783f5a4",
        "provider_terminal_id": "Android Emulator"
    },
    "sequence_number": "PA022ba7",
    "external_location_id": null,
    "merchant_destination_account": null,
    "errors": [
        {
            "code": "ebt_error_43",
            "message": "Lost/stolen card - Cannot Process - Call Customer Service",
            "source": {
                "resource": "Payments",
                "ref": "55ca7f3c35"
            }
        }
    ],
    "previous_errors": [
        {
            "code": "ebt_error_43",
            "message": "Lost/stolen card - Cannot Process - Call Customer Service",
            "source": {
                "resource": "Payments",
                "ref": "55ca7f3c35"
            }
        }
    ],
    "refunds": []
}

The Payment details precede the errors details.

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

Inactive Card - Call number on EBT Card

There’s an issue with the EBT Card number.

ebt_error_14

Invalid card number - Re-enter Transaction

There’s an issue with the EBT Card number.

ebt_error_19

Invalid Card Number - Please re-enter

There’s an issue with the EBT Card number.

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:

{
    "ref": "414d656d28",
    "merchant": "9000034",
    "funding_type": "ebt_snap",
    "amount": "1.00",
    "description": "Testing POS certification app payments (SNAP Purchase)",
    "metadata": {},
    "payment_method": "5d96ef34ac",
    "delivery_address": null,
    "is_delivery": false,
    "created": "2024-05-07T09:02:39.151663-07:00",
    "updated": "2024-05-07T09:03:02.312241-07:00",
    "status": "failed",
    "last_processing_error": null,
    "success_date": null,
    "receipt": {
        "ref_number": "414d656d28",
        "is_voided": false,
        "snap_amount": "1.00",
        "ebt_cash_amount": "0.00",
        "cash_back_amount": "0.00",
        "other_amount": "0.00",
        "sales_tax_applied": "0.00",
        "balance": {
            "id": 231529,
            "snap": "1000.00",
            "non_snap": "1000.00",
            "updated": "2024-05-07T09:03:02.281341-07:00"
        },
        "last_4": "4451",
        "message": "Insufficient funds - Insufficient Funds. Remaining balances are SNAP: $1000.00, EBT Cash: $1000.00",
        "transaction_type": "Payment",
        "created": "2024-05-07T09:03:02.303324-07:00",
        "sequence_number": "PA022b56"
    },
    "expires_at": "2024-05-07T16:33:02.312241Z",
    "pos_terminal": {
        "terminal_id": "0783f5a4",
        "provider_terminal_id": "Android Emulator"
    },
    "sequence_number": "PA022b56",
    "external_location_id": null,
    "merchant_destination_account": null,
    "errors": [
        {
            "code": "ebt_error_51",
            "message": "Insufficient funds - Insufficient Funds. Remaining balances are SNAP: $1000.00, EBT Cash: $1000.00",
            "source": {
                "resource": "Payments",
                "ref": "414d656d28"
            },
            "details": {
                "cash_balance": "1000.00",
                "snap_balance": "1000.00"
            }
        }
    ],
    "previous_errors": [
        {
            "code": "ebt_error_51",
            "message": "Insufficient funds - Insufficient Funds. Remaining balances are SNAP: $1000.00, EBT Cash: $1000.00",
            "source": {
                "resource": "Payments",
                "ref": "414d656d28"
            },
            "details": {
                "cash_balance": "1000.00",
                "snap_balance": "1000.00"
            }
        }
    ],
    "refunds": []
}

ebt_error_52

Inactive Card - Call number on EBT Card

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

Inactive Card - Call number on EBT Card

There’s an issue with the EBT Card number.

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

Invalid Card Number - Please re-enter

There’s an issue with the 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

Inactive Card - Call number on back of EBT Card to activate

There’s an issue with the EBT Card number.

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.

ebt_processor_timeout

Unable to contact EBT processor, please try again shortly.

Prompt the cardholder to try the transaction again in a few minutes.

expired_session_token

deferPaymentCapture returns this error.

This token has expired

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

Refer to request limits documentation for details.

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 funding_type of the Payment.

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.

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.

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.

pin_caching_error

Unable to cache encrypted PIN value

Use the corresponding SDK method to collect a cardholder’s PIN, and then try the transaction again.

pin_retrieval_error

One of several possible messages might accompany this code.

Unable to retrieve encrypted PIN value

or

Unable to find encrypted PIN for key value

or

Refund for payment ref {payment_ref} requires a pin which is missing

Use the corresponding SDK method to collect a cardholder’s PIN, and then try the transaction again.

processor_timeout

External processor timed out

Forage was unable to receive a response from the EBT network. Retry the request. If you keep receiving the error, then increase the amount of time that you wait between retries exponentially.

refund_exceeds_order_total

One of several possible messages might accompany this code.

Requested refund would push the total amount refunded above the original Payment amount. Total amount paid is {amount_paid}. Existing total of refunds is {refund_amount}

or

Requested refund would push the total amount settled to the Merchant above the original Payment amount. Total fixed amount allocated to the Merchant is {}. Existing total of refunds is {}

or

Requested refund would push the total amount settled to the Platform above the original Payment amount. Total fixed amount allocated to the Platform is {}. Existing total of refunds is {}

or

Must allocate funds to merchant_fixed_settlement and platform_fixed_settlement correctly. Merchant funds to be allocated: {merchant_fixed_amount_still_available_for_refund}, Platform funds to be allocated: {platform_fixed_amount_still_available_for_refund}

or

Refund must be greater than zero!

Confirm that the requested refund amount is less than or equal to the original payment amount (or is not equal to zero) and try the refund again.

resource_not_found

deferPaymentCapture returns this error.

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

settlement_greater_than_amount

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

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

too_many_requests

deferPaymentCapture returns this error.

Request was throttled, please try again later.

Refer to request limits documentation for details.

unknown_server_error

Unknown exception from EBT network

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

user_error

deferPaymentCapture returns this error.

A customer submitted incorrect or incomplete information.

Prompt the customer to submit again. For example, in the case that they entered an incomplete pin, you could display a message like, “Invalid EBT Card PIN entered. Please enter your 4-digit PIN.”