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:

• Universal code and message pairs that all endpoints can throw
• Unique pairs that common endpoints can return
• Forage resource values
• HTTP status codes

📘

Errors By Integration Type

Check the errors documentation relevant to your integration type for additional details.

• Custom Integration
• Fully Hosted Integration
• SDK Integration

Universal code and message pairs

Any Forage endpoint can return the following codes.

bad_signature

Bad Token Signature

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

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

expired_session_token

This token has expired

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

expired_token_signature

Expired Token Signature

Create a new authentication token and retry the request.

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

invalid_field_update_error

Immutable fields {invalid_update_fields} cannot be updated

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

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

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

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

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

No merchant account was provided.

Add the Merchant-Account request header.

resource_not_found

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

resource_locked

Request could not be completed because the resource is currently locked. Please try again later.

This means the target resource is temporarily unavailable due to concurrent processing or locking behavior (often related to idempotent operations).

Try again later. Use exponential backoff in your retry logic and ensure your Idempotency-Key is consistent for retries.

secure_storage_inaccessible

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.

too_many_requests

Request was throttled, please try again later.

Refer to request limits documentation for details.

unknown_fields_error

Unknown field(s) provided: {unknown_fields}

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

unknown_server_error

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.

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.

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.

PaymentMethods

The Payment Methods endpoints return the below errors.

cannot_delete_payment_method

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.

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.

Reports

The Reports endpoints return the below errors.

invalid_filters

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

423 - Locked

The target resource is currently locked. This is often caused by concurrent requests using the same Idempotency-Key, or the resource being processed in another operation.

Retry the request using exponential backoff.

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.