Vault API Errors

Vault API error codes and messages help identify validation, authentication, and vault-related issues. Review the cause and resolution details provided for each error to troubleshoot requests and ensure successful API operations.

Error Code	Error Message	Cause	Resolution
400	Please provide a valid APP ID or APP Key	The valor-app-id or valor-app-key header is missing, empty, or longer than 32 characters.	Send both the valor-app-id and valor-app-key headers with the values provided for your merchant account.
400	Not a valid APP ID or APP Key	The APP ID and APP Key combination does not match any active merchant.	Verify the APP ID and APP Key in the merchant portal and send the correct pair.
400	Invalid merchant	The APP ID and APP Key are valid, but no merchant is linked to them.	Contact Valor support to confirm the credentials are linked to an active merchant.
400	You do not have permission to access vault	The Vault module is not enabled for the user linked to these credentials.	Ask your administrator or Valor support to enable the Vault module for the user.
400	Something went wrong	An unexpected error occurred while validating the APP ID and APP Key.	Retry the request. If the error continues, contact Valor support.
400	Vault customer ID missing	The vault_id in the URL is missing or is not a valid number.	Send the numeric vault_id returned in the Add Customer API response.
400	Customer not exist	No customer with this vault_id exists for your merchant, or the customer has been deleted.	Send a valid vault_id of an active customer under your merchant account.
400	Internal server error	An unexpected error occurred while validating the request (for example, loading the state list).	Retry the request. If the error continues, contact Valor support.
400	Customer name is required	The customer_name field is missing or empty in the request payload.	Include a valid customer name in the request payload.
400	Unexpected field(s): <field list>	The request payload contains fields that this API does not accept.	Remove the listed fields. Allowed fields: customer_name, company_name, customer_phone, customer_email, address_details.
400	Customer name must be a string	The customer_name field is not sent as a string.	Send customer_name as a text (string) value.
400	Customer name must not exceed 100 characters	The customer_name value is longer than 100 characters.	Shorten customer_name to 100 characters or fewer.
400	Customer name must contain at least two alphabetic characters	The customer_name value has fewer than two letters (A–Z).	Include a customer name with at least two letters.
400	Enter a valid Customer name	The customer_name value contains < or >, or has fewer than two letters.	Send customer_name with at least two letters, without < or >.
400	Company name must be a string	The company_name field is not sent as a string.	Send company_name as a text (string) value.
400	Company name must not exceed 160 characters	The company_name value is longer than 160 characters.	Shorten company_name to 160 characters or fewer.
400	Enter a valid Company name	The company_name value contains characters that are not allowed.	Send company_name using only letters, numbers, spaces and @ # $ & , . ( ) ' / -.
400	Address label must be a string	The address_label field is not sent as a string.	Send address_label as a text (string) value.
400	Address label must not exceed 100 characters	The address_label value is longer than 100 characters.	Shorten address_label to 100 characters or fewer.
400	Enter a valid Address label	The address_label value contains characters that are not allowed.	Send address_label using only letters, numbers, spaces and @ # $ & , . ( ) ' / -.
400	Billing customer name must be a string	The billing_customer_name field is not sent as a string.	Send billing_customer_name as a text (string) value.
400	Billing customer name must not exceed 100 characters	The billing_customer_name value is longer than 100 characters.	Shorten billing_customer_name to 100 characters or fewer.
400	Billing street number must be a string	The billing_street_no field is not sent as a string.	Send billing_street_no as a text (string) value.
400	Billing street number must not exceed 40 characters	The billing_street_no value is longer than 40 characters.	Shorten billing_street_no to 40 characters or fewer.
400	Enter a valid Billing street number	The billing_street_no value contains characters that are not allowed.	Send billing_street_no using only letters, numbers, spaces, / and -.
400	Billing street name must be a string	The billing_street_name field is not sent as a string.	Send billing_street_name as a text (string) value.
400	Billing street name must not exceed 150 characters	The billing_street_name value is longer than 150 characters.	Shorten billing_street_name to 150 characters or fewer.
400	Enter a valid Billing street name	The billing_street_name value contains characters that are not allowed.	Send billing_street_name using only letters, numbers, spaces and @ # $ & , . ( ) ' / -.
400	Billing unit must be a string	The billing_unit field is not sent as a string.	Send billing_unit as a text (string) value.
400	Billing unit must not exceed 25 characters	The billing_unit value is longer than 25 characters.	Shorten billing_unit to 25 characters or fewer.
400	Enter a valid Billing unit	The billing_unit value contains characters that are not allowed.	Send billing_unit using only letters, numbers, spaces, #, / and -.
400	Billing city must be a string	The billing_city field is not sent as a string.	Send billing_city as a text (string) value.
400	Billing city must not exceed 40 characters	The billing_city value is longer than 40 characters.	Shorten billing_city to 40 characters or fewer.
400	Enter a valid Billing city	The billing_city value contains characters that are not allowed.	Send billing_city using only letters, numbers, spaces, ' . and -.
400	Enter a valid Billing ZIP	The billing_zip value contains characters that are not allowed.	Send billing_zip using only up to 10 letters, numbers, spaces or hyphens.
400	Shipping customer name must be a string	The shipping_customer_name field is not sent as a string.	Send shipping_customer_name as a text (string) value.
400	Shipping customer name must not exceed 100 characters	The shipping_customer_name value is longer than 100 characters.	Shorten shipping_customer_name to 100 characters or fewer.
400	Shipping street number must be a string	The shipping_street_no field is not sent as a string.	Send shipping_street_no as a text (string) value.
400	Shipping street number must not exceed 40 characters	The shipping_street_no value is longer than 40 characters.	Shorten shipping_street_no to 40 characters or fewer.
400	Enter a valid Shipping street number	The shipping_street_no value contains characters that are not allowed.	Send shipping_street_no using only letters, numbers, spaces, / and -.
400	Shipping street name must be a string	The shipping_street_name field is not sent as a string.	Send shipping_street_name as a text (string) value.
400	Shipping street name must not exceed 150 characters	The shipping_street_name value is longer than 150 characters.	Shorten shipping_street_name to 150 characters or fewer.
400	Enter a valid Shipping street name	The shipping_street_name value contains characters that are not allowed.	Send shipping_street_name using only letters, numbers, spaces and @ # $ & , . ( ) ' / -.
400	Shipping unit must be a string	The shipping_unit field is not sent as a string.	Send shipping_unit as a text (string) value.
400	Shipping unit must not exceed 25 characters	The shipping_unit value is longer than 25 characters.	Shorten shipping_unit to 25 characters or fewer.
400	Enter a valid Shipping unit	The shipping_unit value contains characters that are not allowed.	Send shipping_unit using only letters, numbers, spaces, #, / and -.
400	Shipping city must be a string	The shipping_city field is not sent as a string.	Send shipping_city as a text (string) value.
400	Shipping city must not exceed 40 characters	The shipping_city value is longer than 40 characters.	Shorten shipping_city to 40 characters or fewer.
400	Enter a valid Shipping city	The shipping_city value contains characters that are not allowed.	Send shipping_city using only letters, numbers, spaces, ' . and -.
400	Enter a valid Shipping ZIP	The shipping_zip value contains characters that are not allowed.	Send shipping_zip using only up to 10 letters, numbers, spaces or hyphens.
400	Please provide a valid Customer email address	The customer_email value is not a valid email address.	Send a valid email address, for example [email protected].
400	Customer phone must be a 10-digit number	The customer_phone value is not exactly 10 digits.	Send a 10-digit phone number without spaces, dashes or country code.
400	Address details must be an array	The address_details field is not sent as an array.	Send address_details as an array of address objects.
400	Address details can contain a maximum of 5 entries	The address_details array has more than 5 addresses.	Send no more than 5 addresses in address_details.
400	Each entry in address details must be an object	One or more entries in address_details is not an object.	Send each address in address_details as a JSON object.
400	Address label is required	An address in address_details has no address_label.	Include a unique address_label for every address.
400	Duplicate address label found: <address_label>	Two or more addresses in the request use the same address_label.	Use a different address_label for each address.
400	Address ID must contain only numbers	The address_id value is not a whole number.	Send address_id as the numeric ID returned by the Get Customer API, or leave it out for a new address.
400	Unexpected field(s) found in address details: <field list>	An address object contains fields that are not supported.	Remove the listed fields from the address object.
400	Duplicate address detail found: <address_label>	Two or more addresses in the request have exactly the same billing and shipping details.	Remove the duplicate address or change its details.
400	Billing state must be a valid state code	The billing_state value is not a recognized state code.	Send a valid 2-letter state code, for example CA or NY.
400	Shipping state must be a valid state code	The shipping_state value is not a recognized state code.	Send a valid 2-letter state code, for example CA or NY.
400	Cannot add more than 5 address.	Saving these addresses would give the customer more than 5 addresses.	Delete an existing address or reduce the number of addresses in the request.
400	Duplicate address label found	The address_label is already used by another address of this customer.	Use an address_label that is not already used by the customer.
400	Vault ID is required	The customer profile could not be saved, so no vault ID was generated for the new customer. This is a server-side failure; the request does not need a vault ID.	Retry the request. If the error continues, contact Valor support.
400	Invalid Address ID	The address_id does not belong to this customer.	Send an address_id returned by the Get Customer API for this vault_id.
400	vault_id must be a valid positive integer	The vault_id query parameter is not a positive whole number.	Send vault_id as a positive number, or leave it out.
400	search must be a string with maximum 50 characters	The search query parameter is longer than 50 characters.	Shorten search to 50 characters or fewer.
400	customer_name must be a string with maximum 255 characters	The customer_name query parameter is longer than 255 characters.	Shorten customer_name to 255 characters or fewer.
400	email must be a string with maximum 255 characters	The email query parameter is longer than 255 characters.	Shorten email to 255 characters or fewer.
400	phone must be a string with maximum 50 characters	The phone query parameter is longer than 50 characters.	Shorten phone to 50 characters or fewer.
400	company must be a string with maximum 255 characters	The company query parameter is longer than 255 characters.	Shorten company to 255 characters or fewer.
400	email must be a valid email format	The email query parameter is not a valid email address.	Send a valid email address, for example [email protected].
400	total_card_count_min must be a valid positive integer	The total_card_count_min query parameter is not a positive whole number.	Send total_card_count_min as a positive whole number.
400	total_card_count_max must be a valid positive integer	The total_card_count_max query parameter is not a positive whole number.	Send total_card_count_max as a positive whole number.
400	total_recursive_billing_min must be a valid positive integer	The total_recursive_billing_min query parameter is not a positive whole number.	Send total_recursive_billing_min as a positive whole number.
400	total_recursive_billing_max must be a valid positive integer	The total_recursive_billing_max query parameter is not a positive whole number.	Send total_recursive_billing_max as a positive whole number.
400	transaction_count_min must be a valid positive integer	The transaction_count_min query parameter is not a positive whole number.	Send transaction_count_min as a positive whole number.
400	transaction_count_max must be a valid positive integer	The transaction_count_max query parameter is not a positive whole number.	Send transaction_count_max as a positive whole number.
400	last_txn_date_before must be a valid date in YYYY-MM-DD format	The last_txn_date_before query parameter is not a valid date.	Send last_txn_date_before in YYYY-MM-DD format, for example 2026-01-31.
400	last_txn_date_after must be a valid date in YYYY-MM-DD format	The last_txn_date_after query parameter is not a valid date.	Send last_txn_date_after in YYYY-MM-DD format, for example 2026-01-31.
400	total_card_count_min cannot be greater than total_card_count_max	total_card_count_min is greater than total_card_count_max.	Send a total_card_count_min value that is less than or equal to total_card_count_max.
400	total_recursive_billing_min cannot be greater than total_recursive_billing_max	total_recursive_billing_min is greater than total_recursive_billing_max.	Send a total_recursive_billing_min value that is less than or equal to total_recursive_billing_max.
400	transaction_count_min cannot be greater than transaction_count_max	transaction_count_min is greater than transaction_count_max.	Send a transaction_count_min value that is less than or equal to transaction_count_max.
400	last_txn_date_after cannot be later than last_txn_date_before	last_txn_date_after is a later date than last_txn_date_before.	Send a last_txn_date_after that is on or before last_txn_date_before.
400	No Data Found	No customers match the filters, or no customers exist for the merchant.	Change or remove the filters, or add customers first.
400	Unable to delete the customer profile.	The customer could not be deleted (it may already be deleted).	Check the vault_id with the Get Customer API and retry.
400	Vault address ID missing	The address_id in the URL is missing or is not a valid number.	Send the numeric address_id returned by the Get Customer API.
400	Invalid vault address ID	The address_id does not belong to this customer.	Send an address_id returned by the Get Customer API for this vault_id.
400	Vault address ID already deleted	The address has already been deleted.	No action needed. Use the Get Customer API to see the current addresses.
400	Unable to delete the address.	The address could not be deleted.	Check the address_id with the Get Customer API and retry.
400	No Data Found	No customer details were found for this vault_id under your merchant.	Send a valid vault_id of an active customer.
400	No record Found	The customer record could not be found for this vault_id.	Send a valid vault_id of an active customer.
400	No record found	The customer details returned are empty.	Send a valid vault_id of an active customer.
400	Card number is required	The pan_num field is missing from the request payload.	Include the card number in the pan_num field.
400	Expiry date is required	The expiry field is missing from the request payload.	Include the card expiry date in the expiry field (MM/YY or MMYY).
400	Unexpected field(s): <field list>	The request payload contains fields that this API does not accept.	Remove the listed fields. Allowed fields: pan_num, expiry, cardholder_name, is_validate_card.
400	Card number must be between 13 and 19 digits	The pan_num value is shorter than 13 or longer than 19 digits.	Send a card number of 13 to 19 digits with no spaces or dashes.
400	Card number is invalid	The pan_num value fails the card number check (Luhn).	Check the card number and send it again.
400	Card number cannot have all digits the same	Every digit in pan_num is the same (for example 4444444444444).	Send a real card number.
400	Expiry date must be in MM/YY or MMYY format	The expiry value is not in MM/YY or MMYY format.	Send the expiry date as MM/YY (for example 08/28) or MMYY (for example 0828).
400	Expiry date is invalid	The expiry month is not valid or the card has already expired.	Send a valid month (01–12) and a future expiry date.
400	Cardholder name contains invalid or malicious characters	The cardholder_name contains HTML, script or other unsafe characters.	Send the cardholder name using only letters and spaces.
400	Cardholder name contains only invalid characters	The cardholder_name has no valid characters after unsafe characters are removed.	Send the cardholder name using only letters and spaces.
400	Cardholder name must be at least 5 characters	The cardholder_name is shorter than 5 characters.	Send a cardholder name of 5 to 25 characters.
400	Cardholder name must be a string	The cardholder_name is not sent as a string.	Send cardholder_name as a text (string) value.
400	Cardholder name must not exceed 25 characters	The cardholder_name is longer than 25 characters.	Send a cardholder name of 5 to 25 characters.
400	Cardholder name can only contain letters and spaces	The cardholder_name contains numbers or special characters.	Send the cardholder name using only letters and spaces.
400	The is_validate_card field must be either true or false	The is_validate_card value is not a boolean.	Send is_validate_card as true or false (without quotes), or leave it out.
400	Cannot add more than 5 cards	The customer already has 5 payment profiles.	Delete an existing payment profile before adding a new one.
400	Unable to add payment profile	The card could not be saved. The merchant may not have an active EPI, or the card could not be tokenized.	Check that the merchant has an active terminal (EPI) and the card details are correct, then retry. If the error continues, contact Valor support.
400	<Processor error message>	The card was declined or rejected during tokenization. The message comes from the payment processor (for example, INVALID CARD NUMBER).	Correct the card details based on the message and retry. If the error continues, contact Valor support.
400	Vault payment profile ID missing	The profile_id in the URL is missing or is not a valid number.	Send the numeric payment_id returned by the Add Payment Profile API as the profile_id in the URL (they are the same value).
400	Please provide a valid payment profile ID	The profile_id does not belong to this customer.	Send a payment_id returned by the Get Payment Profile API for this vault_id.
400	Unable to update payment profile	The card could not be updated. The merchant may not have an active EPI, or the card could not be tokenized.	Check that the merchant has an active terminal (EPI) and the card details are correct, then retry.
400	Payment profile ID has already been deleted	The payment profile has already been deleted.	No action needed. Use the Get Payment Profile API to see the current profiles.
400	Unable to delete the payment profile	The payment profile could not be deleted.	Check the profile_id with the Get Payment Profile API and retry.
400	Missing required field(s): status	The status field is missing from the request payload.	Include status with the value active or inactive.
400	Unexpected field(s): <field list>	The request payload contains fields other than status.	Send only the status field.
400	Invalid value for status. Allowed values are: active, inactive	The status value is not active or inactive.	Send status as active or inactive.
400	Invalid payment profile ID	The profile_id does not belong to this customer.	Send a payment_id returned by the Get Payment Profile API for this vault_id.
400	Unable to update the payment profile.	The payment profile status could not be updated.	Check the profile_id with the Get Payment Profile API and retry.
400	Reference transaction ID missing	The ref_txn_id field is missing from the request payload.	Include the ref_txn_id returned in the Sale or Auth API response.
400	Invalid reference transaction ID	The ref_txn_id was not found or does not belong to your merchant.	Send a valid ref_txn_id from a transaction processed by your merchant.
400	Reference transaction ID is not supported	The transaction was not approved, or its type is not SALE, AUTH, REFUND or COMPLETION.	Send the ref_txn_id of an approved SALE, AUTH, REFUND or COMPLETION transaction.
400	Reference transaction ID date must be within the last 30 days	The referenced transaction is older than 30 days.	Send the ref_txn_id of a transaction processed in the last 30 days.
400	Missing required field(s): token	The token field is missing from the request payload.	Include the card token in the token field.
400	Unexpected field(s): <field list>	The request payload contains fields that this API does not accept.	Remove the listed fields. Allowed fields: token, cardholder_name.
400	Enter a valid Token	The token value is not in a valid format.	Send the token exactly as returned by the tokenization API.
400	Token already exists	This token is already saved for the customer.	Use the existing payment profile, or send a different token.
400	Invalid Token	The processor did not recognize the token.	Generate a new token and retry.
400	Invalid start date format. Please provide a valid start date in the format YYYY-MM-DD.	The start_date is not a valid date in YYYY-MM-DD format.	Send start_date in YYYY-MM-DD format, for example 2026-01-01.
400	Invalid end date format. Please provide a valid end date in the format YYYY-MM-DD.	The end_date is not a valid date in YYYY-MM-DD format.	Send end_date in YYYY-MM-DD format, for example 2026-01-31.
400	Invalid start date. The start date cannot be in the future.	The start_date is later than today.	Send a start_date of today or earlier.
400	Invalid date range. The start date cannot be greater than the end date.	The start_date is later than the end_date.	Send a start_date that is on or before the end_date.
400	Invalid date range. The transaction date range must fall within the last 90 days.	The date range includes dates older than 90 days.	Send dates within the last 90 days.
400	Invalid date range. Please select a date range within 30 days.	The range between start_date and end_date is longer than 30 days.	Send a date range of 30 days or less.
400	No Data Found	No transactions were found for the customer in the selected date range.	Try a different date range.
400	File is required.	No file was attached to the request.	Attach the customer file (.xlsx, .xls or .csv) as multipart/form-data.
400	Invalid file format	The file extension is not supported.	Upload a .xlsx, .xls or .csv file.
400	Blocked file type not allowed	The file type is blocked for security reasons.	Upload a .xlsx, .xls or .csv file created from the sample template.
400	Unsafe filename detected	The file name contains unsafe characters (for example ../ or special characters).	Rename the file using only letters, numbers, hyphens and underscores, then upload it again.
400	File too large	The file is larger than 150 KB.	Reduce the file size to 150 KB or less, or split it into smaller files.
400	File uploaded already in queue. Your current customer list upload is in progress. Once it is completed, you can upload the next file.	A previous upload for this user is still being processed.	Wait for the email confirming the previous upload is processed, then upload the next file.
400	Error while uploading file.	The file could not be uploaded because of an unexpected error.	Retry the upload. If the error continues, contact Valor support.
400	Missing required field(s): <field list>	One or more required fields are missing. Add/Update require account_number, routing_number, payee_name, account_type and entry_class.	Include all the listed fields in the request.
400	Unexpected field(s): <field list>	The request payload contains fields that this API does not accept.	Remove the listed fields. Add allows account_number, routing_number, payee_name, account_type, entry_class, ecomm_ach_auth; Update allows the same without ecomm_ach_auth.
400	account_number must be numeric with a maximum of 18 digits	The account_number contains non-digits or is longer than 18 digits.	Send the bank account number using digits only, up to 18 digits.
400	routing_number must be numeric with a maximum of 9 digits	The routing_number contains non-digits or is longer than 9 digits. Bank routing numbers are always exactly 9 digits.	Send the 9-digit bank routing number using digits only.
400	Payee name must not exceed 30 characters	The payee_name is longer than 30 characters.	Send a payee name of 30 characters or fewer.
400	Payee name cannot be only numbers	The payee_name contains only numbers.	Send a payee name that includes letters.
400	Payee name cannot be only special characters	The payee_name contains only special characters.	Send a payee name that includes letters.
400	Payee name must include at least one letter	The payee_name has no letters.	Send a payee name that includes at least one letter.
400	Enter a valid Payee name	The payee_name contains < or >.	Remove < and > from the payee name.
400	account_type must be either C or S	The account_type is not C or S.	Send C for a checking account or S for a savings account.
400	entry_class must be either Business or Personal	The entry_class is not Business or Personal.	Send entry_class as Business or Personal.
400	ecomm_ach_auth must be 1	The ecomm_ach_auth field was sent with a value other than 1.	Send ecomm_ach_auth as 1, or leave it out.
400	Vault ACH profile ID missing	The ach_profile_id in the URL is missing or is not a valid number.	Send the numeric ach_profile_id returned by the Add ACH Profile API.
400	You do not have permission to access ACH	ACH is not enabled for the merchant.	Contact Valor support to enable ACH for your merchant account.
400	Cannot add more than 5 ach details	The customer already has 5 ACH profiles.	Delete an existing ACH profile before adding a new one.
400	ACH profile ID does not exist	The ach_profile_id does not belong to this customer or has been deleted.	Send an ach_profile_id returned by the Get ACH Profile API for this vault_id.
400	No changes detected. ACH profile already contains the same information	The update request has the same details as the saved ACH profile.	Change at least one field before updating.
400	ACH information already exists	An ACH profile with the same account and routing number already exists for the customer.	Use the existing ACH profile, or send different bank details.
400	ACH validation failed. Please check the account and routing number	The bank account and routing number could not be verified.	Check the account number and routing number with the customer and retry.
400	Customer information incomplete. Please update the phone number or email address.	The customer has no phone number or email address to send the ACH authorization to.	Update the customer with a phone number or email using the Edit Customer API, then retry.
400	Failed to send ACH authorization	The ACH authorization request could not be sent to the customer.	Check the customer phone number and email, then retry. If the error continues, contact Valor support.

Showing 166 of 166 entries