Errors and error handling

Understanding API errors

When a request to the Helcim API results in an error response, the respective endpoint will return a response with an 'errors' object containing any relevant error messages. These will be returned with an appropriate HTTP response code in order for you to handle the error within your integration appropriately.

The Helcim API can return one or more errors within the same errors object, and each error may require a different resolution before submitting your request again. The key of each error message within the object will often correlate to the field within the request where the error originated, while the value will provide more information on why the error occurred.

Depending on the root cause of Helcim API errors, you may need to resolve these by changing Helcim account settings, or updating the information sent in the header or body of your request.

Authentication

The following are some common errors that could be encountered when integrating with the Helcim API.

Unauthorized

This status 401 error response will be returned if you have attempted a request with an invalid or inactive api-token.

• Confirm your api-token is correct and active, in the Integrations section of your Helcim account, then attempt your request again.

{
    "errors": "Unauthorized"
}

No access permission

You have attempted a request that requires permissions that the API token passed in the request is not allowed to complete. Update your token permissions in the Integrations section of your Helcim account and attempt your request again.

{
    "errors": "No access permission"
}

Payment API

The following are some common errors that could be encountered when integrating with the Payment API.

Not allowed to send full card number

This status 401 error response will be returned if you have attempted to process a transaction using a full card number and are not approved to do so.

• Utilize HelcimPay.js or Helcim.js to tokenize card details and send a cardToken in the cardData object instead of the card details.
• Review our documentation on understanding PCI compliance to learn more.

{
  "errors": "Not allowed to send full card number"
}

Missing required cardData

This status 400 error response is returned when a request is sent to the Payment API and a required cardData object is missing.

Please note that the API will respond to indicate that the cardNumber, cardExpiry, and cardCVV are missing, even if not approved for full card numbers.

• Please send either a card object containing a cardNumber, cardExpiry, and cardCVV (if approved to process with full card numbers) or a cardToken to resolve this error.

{
  "errors": {
    "cardData[cardNumber]": "Missing required data card Data.card Number",
    "cardData[cardExpiry]": "Missing required data card Data.card Expiry",
    "cardData[cardCVV]": "Missing required data card Data.card CVV"
  }
}

Missing required data

This status 400 error response is returned when a request is missing a required data object. This is most commonly caused by a billingAddress object being missed in the request.

• Review the key of error response to locate the required missing data from your request and include this information for sending your request again.

{
  "errors": {
    "billingAddress": "Missing required data billing Address"
  }
}

Missing idempotency key

This status 400 error response is returned if you have attempted to process a transaction without sending a valid idempotency key with your request.

• Generate a new idempotency-key and send this in the header of your request before attempting your request again. Review our article on Idempotency for more information on how to generate these.

invalid idempotencyKey

Invoice API

The following are some common errors that could be encountered when integrating with the Invoice API.

Missing required data

This status 400 error response is returned if a required data object for your request is incomplete. This error can be triggered by a range of required parameters in invoice data objects being missing from your request and the errors object will outline what data object is missing.

• Include the missing required data before trying the request again.

{
  "errors": {
    "lineItems[0][price]": "Missing required data line Items.0.price"
  }
}

Invalid line items

This status 400 error response is returned if you fail to provide valid line items in the form of an array of objects. If no lineItems are provided in the request you will receive an "Invalid line items" response from the API.

• Add your line items before attempting your request again.

{
  "errors": {
    "lineItems": "INVALID LINE ITEMS"
  }
}

Customer API

The following are some common errors that could be encountered when integrating with the Customer API.

Missing required data

When a required value is not sent in your Create customer request, the Helcim system will respond with an errors object that contains parameters indicating which required values were missed. Ensure your request contains the required values before attempting your request again.

{
  "errors": {
    "billingAddress[name]": "Missing required data billing Address.name",
    "billingAddress[postalCode]": "Missing required data billing Address.postal Code"
  }
}

Invalid phone number

The Helcim system will do basic validation on the string value passed for cellPhone, to ensure that it is between 10 and 16 characters long. Values that are shorter or longer than this restriction will return a errors object. Ensure your request contains a cellPhone value that meets the length requirements before attempting your request again.

{
  "errors": {
    "cellPhone": "cell Phone must be a valid Phone Number"
  }
}