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:
- Universal
code
andmessage
pairs that all endpoints can throw - Unique pairs that common endpoints can return
- Forage
resource
values - HTTP status codes
Additional errors by integration type
Be sure to also consult the errors documentation specific to your integration type:
Universal code
and message
pairs
code
and message
pairsAny Forage endpoint can return the following codes.
bad_signature
bad_signature
Bad Token Signature
Create a new authentication token and retry the request.
cannot_change_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_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
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
Expired Token Signature
Create a new authentication token and retry the request.
forbidden_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
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
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
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
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
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
missing_merchant_account
No merchant account was provided.
Add the Merchant-Account
request header.
resource_not_found
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.
secure_storage_inaccessible
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
too_many_requests
Request was throttled, please try again later.
Refer to request limits documentation for details.
unknown_fields_error
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_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
code
and message
pairs for common endpointsBearer Tokens
The Bearer Tokens endpoints return the below errors.
invalid_expiration_time
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
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
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
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
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
resource
valuesThe 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.