Errors and error handling

The Recurring API follows a newly implemented error response format for Helcim. This format ensures consistent error responses between endpoints and will be the foundation for all future versions and net new functionality to the Helcim API.

Error response format

An error response will be returned for any request that has invalid or missing parameters or values, is not from an authorized source, contains an api-token with insufficient permissions, or where an internal server error is encountered.

Any error response from the Recurring API will be returned as a JSON object that contains:

• A timestamp with the date of the error in UTC time.
• A status of "error".
• An errors object array containing one or more error types.

Each error type will contain an array of objects for the error being returned. The error object may contain:

• A code value for each unique error type.
• A message value providing general information on the error.
• A source value indicating the parameter where the error was generated.
• A data value indicating the value passed where the error was generated and why the error was generated.

Common error responses

The following are some of the common error responses that you may encounter when integrating with the Recurring API, including some examples of the response format outlined above.

ERR_VALIDATION_FAILED

This status 400 response is returned if the request contains an invalid or missing body parameter. The response will contain information on the cause and location of the errorm, which should be corrected before trying again.

// Example Recurring API error response

{
  "timestamp": "2024-10-03T09:36:44.704712059-06:00",
  "status": "error",
  "errors": {
    "ERR_VALIDATION_FAILED": [
      {
        "code": "ERR_VALIDATION_FAILED",
        "message": "Field fails validation",
        "source": "Name",
        "data": ""
      }
    ]
  }
}

ERR_UNAUTHENTICATED

This status 401 error response is returned if the request does not contain a valid api-token in the header. Check that you have a valid Helcim api-token sent in the header of your request before trying again.

{
  "timestamp": "2024-10-04T08:52:04.14809569-06:00",
  "status": "error",
  "errors": {
    "ERR_UNAUTHENTICATED": [
      {
        "code": "ERR_UNAUTHENTICATED",
        "message": "Requester is unauthenticated"
      }
    ]
  }
}

ERR_UNAUTHORIZED

This status 403 error response is returned if the request contains an api-token with insufficient permissions to action the request. Check that you have the appropriate permissions for your API Access Configuration before trying again.

{
  "timestamp": "2024-10-04T08:52:04.14809569-06:00",
  "status": "error",
  "errors": {
    "ERR_UNAUTHORIZED": [
      {
        "code": "ERR_UNAUTHORIZED",
        "message": "You are not authorized to access this resource."
      }
    ]
  }
}

ERR_INVALID_REQUEST

This status 400 error response is returned if the request contains malformed header or body parameters, including a poorly formatted request, or parameters containing an incorrect data type. Check the source of the error for poor formatting or incorrect data types before trying again.

{
  "timestamp": "2024-10-04T12:54:23.576858557-06:00",
  "status": "error",
  "errors": {
    "ERR_INVALID_REQUEST": [
      {
        "code": "ERR_INVALID_REQUEST",
        "message": "Request is malformed",
        "source": "body",
        "data": "one or more fields have the incorrect data type"
      }
    ]
  }
}

ERR_INTERNAL

This status 500 error response is returned if a Helcim internal server error is encountered. Please reach out to the Helcim Tier 2 Technical Support team with the full request and response payloads for further assistance.

{
  "timestamp": "2024-10-04T08:52:04.14809569-06:00",
  "status": "error",
  "errors": {
    "ERR_INTERNAL": [
      {
        "code": "ERR_INTERNAL",
        "message": "An internal error has occurred"
      }
    ]
  }
}

Invalid idempotency key

This status 409 error response is returned if the request received contains an idempotency-key that has been used on a previously submitted request. Retrieve the object from the API to view the outcome of the payment attempt.

{
  "message": "the request received conflicts with a previous request accepted by the API, often caused by an idempotency key that has been assigned to an existing successful transaction"
}