Error codes

Forage uses HTTP status codes to indicate the success or failure of an API requests. We support the following of status codes.

  • 200 - OK, your request was accepted, and returned the requested data.
  • 201 - Created, your request was accepted, and successfully created a new resource.
  • 204 - No content, your request has succeeded, and there is no additional content to send in the response.
  • 400 - Bad request, your request can't be fulfilled due to a non-valid request body.
  • 401 - Unauthorized, your request didn't provide credentials to authenticate it.
  • 403 - Forbidden, attached credentials to your request don't have enough permissions or had expired.
  • 404 - Not Found, the resource you requested doesn't exist.
  • 429 - Too many requests, request rate limit was reached.
  • 50x - Server error, Forage server issues that are independent of the request. These can encompass server outages as well as issues connecting to the EBT Processing Network. If you receive a 50x response, the issue may be temporary, so we suggest that you retry your request (with the same idempotency key), using exponential backoff.

Error Responses

If the HTTP status code is greater than 399, then the response body from the Payments API will contain an error object of a standard form (all values are strings),

    "code" : "<one of the error codes below>",
    "message" : "<A long string with a more specific description and context>",
    "source" : {
        "resource" : "<one of the resource names below, if available>",
        "ref" : "<the 10 character ref of the resource that caused the error>"

The only exceptions to this rule are 401 and 403 responses, which will only have a detail key in the response body. 401 and 403 responses are only produced by issues with the Bearer authentication token.

Resource Names

The resource key in the error response above can have one of the following values,

  • Orders
  • Payments
  • Payment_Methods
  • Refunds
  • Sessions
  • Merchants
  • Idempotency_Key
  • Authentication_Token
  • Merchant_Account_Header
  • Tenants
  • Reports

Error codes

Our API would return a status code different than 2xx whenever there is a problem with your request or a server error; an error response will include an error code and message explaining what went wrong. You can find in the following table the error codes that might be returned by the Forage Payments API.

HTTP StatusError CodeDescription
400cannot_parse_request_bodyParsing "<field name>" field failed with message: <message>. API was not able to parse request body for 1 or more fields.
400invalid_merchant_account The provided Merchant FNS number is not a valid Merchant on Forage.
400missing_idempotency_key You must include a value for the IDEMPOTENCY-KEY header in your requests to this endpoint and your request is missing Idempotency-Key header and/or the key value.
400missing_merchant_account No merchant account FNS number was provided. Your request is missing Merchant-Account header and/or the Merchant FNS number.
401- Authentication credentials were not provided. Your request is missing Authorization header and/or the Bearer access token.
403invalid_token You do not have permission to perform this action. The provided Bearer access token is not valid, expired or was revoked.
404resource_not_found <Resource type> with ref ########## does not exist for current Merchant with FNS ####### in the Merchant-Account header.
500unknown_server_error An internal server error, non related to your request, happened while processing
400cannot_change_requestYou submitted two different request bodies with the same idempotency key
400no_payments_on_captureAn Order cannot be captured with no associated Payment objects (Payments indicate how much should be paid with each payment method)
400exceeds_snap_totalThe sum of Payment.snap_amount for all Payments associated with the order is greater than Order.snap_total
400exceeds_ebt_cash_totalThe sum of Payment.non_snap_amount for all EBT Payments associated with the order is greater than Order.ebt_cash_total
400wrong_payment_totalSum of Payment amounts on the order does not equal the order total
500unkown_pin_failurePIN entry failed, but no specific error was returned by the EBT network
400balance_check_only_ebtBalance checks can only be performed for PaymentMethods of type ebt
500ebt_network_unresponsiveThe EBT processor for the relevant state is not responding to requests from Forage's server
400duplicate_payment_methodYou attempted to POST a second Payment object which references the same PaymentMethod as another Payment on this order
400cannot_update_paymentYou attempted to update a Payment object which has already been captured (at least partially)
400payment_already_capturedYou attempted to cancel a Payment object which has already been captured (at least partially)
400refund_exceeds_snapYour Refund attempt would increase the total amount refunded to the SNAP balance of the EBT card past the amount that was originally charged to the SNAP balance for this Order.
400refund_exceeds_non_snapYour Refund attempt would increase the total amount refunded to the EBT Cash balance of the EBT card past the amount that was originally charged to the Cash balance for this Order.
400cannot_refund_after_90_daysPer federal guidelines, you cannot refund an EBT payment method more than 90 days after the charge was processed
400order_not_succeededYou cannot bulk refund an Order (with the refund_all endpoint) that is not in the succeeded state
400wait_for_batch_refundYou cannot bulk refund an Order (with the refund_all endpoint) while there are still some Refunds associated with this Order in the processing state.
400order_already_refundedYou cannot bulk refund an Order (with the refund_all endpoint) that is already fully refunded
400cannot_capture_orderOnly orders in the draft or failed states can be submitted for capture. This error code can also arise if your banking information has not been set up in the Payments API backend.
400cannot_cancel_orderOnly orders in the draft or failed states can be canceled.
400cannot_update_orderOrders which have been canceled cannot be updated.
400order_is_cancelledOrders which have been canceled cannot have new Payment objects associated with them.
400invalid_filtersThe filters on your reporting request could not be parsed.
500secure_storage_inaccessibleThe secure storage used in Forage's proprietary PIN solution is not available. Please try again shortly as this error is temporary.
400missing_stripe_client_secretThe client secret field is needed to process Payments through Stripe as the credit/debit TPP
400stripe_errorCalls to the Stripe API returned an unknown error code
400 or 50xebt_error_XXThe XX will be replaced with a 2-digit code from the EBT network. Expand the 400 error description in our docs to see possible values and their meanings.
400 or 500Some errors returned by the Stripe API (for credit/debit only) are piped back in the response to your original request, on the /capture or /refunds endpoints. The full list of possible errors from the Stripe API are here, although only a subset apply to Forage's integration which only makes use of the PaymentIntent, PaymentMethod, Customer, and Refunds objects on Stripe.