Errors

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),

{
  "path": "/api/endpoint",
  "errors": [
    {
      "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.

EBT-related error codes

The following errors are returned in response to EBT-related issues.