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 re-submitting your request. 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.
![api response](https://files.readme.io/3308b7b-image.png)
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 API request.
Common Errors
Connection and Authentication
Unauthorized: 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. For more information on creating or checking an API token, visit our documentation here.
![connection and authentication](https://files.readme.io/a4f2d62-image.png)
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. For more information on configuring API permissions, visit our documentation here.
![no access permission](https://files.readme.io/916e52e-image.png)
Helcim API
Payment API
Error Message | Status | Description |
---|---|---|
Failed to process transaction | 500 | You have attempted to process a credit card transaction using a cardToken that is not associated with the API token, Helcim account, or customerCode that you have passed in your request. Check your Customer section in your Helcim account to confirm that the cardToken is correct before attempting your request again. Helcim developer test accounts are unable to process test ACH transactions and this error will be returned if attempted. |
Not allowed to send full card number | 401 | 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. |
Missing required cardData | 400 | When a request is sent to the Payment API and a required card or cardToken object is missing, the API will respond with a "Missing required data" error object. Please note that if neither potential cardData object is provided, 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 or cardToken to resolve this error based on your accounts approval for sending full card numbers. |
Missing required data | 400 | The Helcim API will respond with a "Missing required data" error when a data object required for your request is missed. In addition to cardData as outlined above, this error can be triggered by a range of required data objects being missing from your request. The errors object will outline what data object is missing. |
Missing idempotency key | 400 | 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. |
Failed to retrieve card transaction | 400 | When attempting to capture, refund, or reverse a transaction, the Helcim API will return a "Failed to retrieve card transaction" error, if the transactionId does not match any transaction in your Helcim account. Check your transactionId is correct through your Helcim account, or the Card Transaction API before attempting your request again. |
Disabled achSetting | 401 | If you attempt to send a request to the Process Withdraw Transaction endpoint and your account does not have ACH Bank Payments enabled, the API will return an error response of Disabled achSetting. To resolve this error, log into your Helcim account and go to Settings, then ACH Bank Payment Settings, in order to toggle on "Enable ACH Bank Payments" for your Helcim account. Please note that some accounts are restricted from processing through ACH entirely and you should review our Acceptable Use Policy if this setting is not available for you. |
Card Batch API
Error Message | Status | Description |
---|---|---|
Card batch not found | 404 | The Get Card Batches API endpoint will respond with a "Card batch not found" error if a specific batchNumber and / or terminalId provided in the request cannot be found in your Helcim account. Check your batchNumber or terminalId is valid through your Helcim account before attempting your request again. Please note that the batchNumber and the cardBatchId are not the same. |
Failed to retrieve card batch with ID | 500 | The Get Card Batch API endpoint will respond with a "Failed to retrieve card batch with ID" error if the cardBatchId passed in the request cannot be found in your Helcim account. Check your cardBatchId is correct before attempting your request again. Please note that the batchNumber and the cardBatchId are not the same. |
Card batch already closed | 400 | The Settle an Open Card Batch API endpoint will respond with a "Card batch already closed" error if the passed cardBatchId belongs to an already settled card batch. No further action is required. |
Card Transaction API
Error Message | Status | Description |
---|---|---|
Empty response | 200 | The Card Transaction API will respond with an empty array if the query params used in the request do not locate any transactions that meet the filtering criteria. |
Failed to retrieve card transaction | 400 | The Get Card Transaction by id API endpoint will respond with a "Failed to retrieve card transaction" error if a specific cardTransactionId provided in the request cannot be found in your Helcim account. Confirm the transactionId is correct through your Helcim account, before attempting your request again |
Customer API
Error Message | Status | Description |
---|---|---|
Customer does not exist | 404 | The Get customers API endpoint will return an error of "Customer does not exist" if the customerCode or search params included in the request cannot locate data in your Helcim account that matches your request. Confirm the correct values are being passed before attempting your request again. |
Customer not found | 404 | The Get customer, Update customer, and Get customer cards API endpoints will return an error of "Customer not found" if the customerId value passed in your request cannot be located in your Helcim account. Confirm the customerId number is correct through your Helcim account, before attempting your request again. Please note that the customerCode and customerId are not the same values. |
Missing required data | 400 | The Create customer API endpoint will respond with a "Missing required data" error when a data object required for your request is missed. This error can be triggered by a range of required data objects being missing from your request. The errors object will outline what data object is missing. |
Empty response | 404 | The Get customer card API endpoint will respond with an empty array if the cardId value does not locate card details for the customerId provided in the request. Confirm the cardId is correct through your Helcim account before attempting the request again. |
Invoice API
Error Message | Status | Description |
---|---|---|
Empty response | 404 | The Get invoices API endpoint will respond with an empty array if the query parameters provided in the request do not locate any matching Invoice data in your Helcim account. Confirm your query parameters are correct before attempting your request again. |
Invoice number already existed | 400 | The Create invoice API endpoint will respond with an "Invoice number already existed" error message if the invoiceNumber provided in the request already exists in your Helcim account. Please change your invoice number before trying the request again. |
Missing required data | 400 | The Create invoice API endpoint will respond with a "Missing required data" error message when a data object required for your request is missed. This error can be triggered by a range of required 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. |
Invalid line items | 400 | The Create invoice API endpoint requires you 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. |
Updated 3 months ago