Log In


Reference documentation for Forage Payments API errors

If something goes wrong during a request, the Forage Payments API responds with an HTTP status code and an errors array 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": ""

On this reference page, you'll find:

Additional errors by integration type

Be sure to also consult the errors documentation specific to your integration type:

Universal code and message pairs

Any Forage endpoint can return the following codes.


Bad Token Signature

Create a new authentication token and retry the 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 the request.

Check the endpoint’s reference documentation and confirm that the request body meets all of the requirements.


This token has expired

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


Expired Token Signature

Create a new authentication token and retry the request.


N/A - no message

This user is unauthorized, or the request was sent client-side to a server-only endpoint. Check your authentication credentials and retry the request.


Immutable fields {invalid_update_fields} cannot be updated

Remove the immutable fields from the request body and try again.


Validation errors.

Double check the endpoint’s reference documentation to validate the request body, and scan your implementation for any other errors.


Merchant account FNS number not valid.

Confirm that the FNS number, most often passed in the Merchant-Account header of the request, is accurate.


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.


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.


No merchant account was provided.

Add the Merchant-Account request header.


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


Temporarily unable to access data in secure storage. Please try again.

Retry the request. If you keep receiving the error, then increase the amount of time that you wait between retries exponentially.


Request was throttled, please try again later.

Refer to request limits documentation for details.


Unknown field(s) provided: {unknown_fields}

Remove the unknown fields from the request body and retry the request.


Unknown exception from EBT network

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

code and message pairs for common endpoints

Bearer Tokens

The Bearer Tokens endpoints return the below errors.


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.


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.


The Payment Methods endpoints return the below errors.


This payment method has already been used in an order and therefore cannot be deleted. {number_of} Payment objects currently reference this payment method, including: {payment_ref}.

No action required.


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.


The Reports endpoints return the below errors.


{filter}: required filter is missing

Check the specific endpoint’s reference documentation to confirm that you’ve provided all of the required parameters, and try the request again.

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

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.