API Error Codes Reference

Auto-generated. Do not edit manually.

Agent Object Error Codes

Location

See details

Error Code Summary

Error Title Reference	Error Title	HTTP Status	Detail Message	Scenario	Resolution
First Name Validation	INVALID_REQUEST	400 BAD REQUEST	agent.firstName cannot be more than 50 characters	When first name exceeds 50 characters	Ensure the agent's first name is 50 characters or less
Last Name Validation	INVALID_REQUEST	400 BAD REQUEST	agent.lastName cannot be more than 50 characters	When last name exceeds 50 characters	Ensure the agent's last name is 50 characters or less
User ID Validation	INVALID_REQUEST	400 BAD REQUEST	agent.userId is required	When agent user ID is missing, null or empty	Include a valid agent.userId in the request

Consent Object Error Codes

Location

See details

Error Code Summary

Error Title Reference	Error Title	HTTP Status	Detail Message	Scenario	Resolution
Merchant Consent Text Validation	INVALID_REQUEST	400 BAD REQUEST	Consent is Invalid!	Merchant consent text is invalid or contains unsupported characters	Remove special characters from consent text
Merchant Consent Id Validation	INVALID_REQUEST	400 BAD REQUEST	merchantConsentId is required	Merchant consent id is missing or invalid	Provide a valid merchant consent ID in the request
Consent Collection Timestamp Validation	INVALID_REQUEST	400 BAD REQUEST	collectionTimestamp is required	Consent collection timestamp is missing or invalid	Include a valid collection timestamp in ISO 8601 format
Consent Collection Details Validation	INVALID_REQUEST	400 BAD REQUEST	collectionDetails are not valid	Consent collection details are missing or invalid	Provide complete and valid collection details
Agent Object Requirement with PPD Consent	INVALID_REQUEST	400 BAD REQUEST	agent object is required with PPD consent	PPD consent requires agent object information	Include agent object with all required fields when using PPD consent

Customer Object Error Codes

Location

See details

Error Code Summary

Error Title Reference	Error Title	HTTP Status	Detail Message	Scenario	Resolution
Identifier Validation
Missing Required Identifiers	INVALID_REQUEST	400 BAD REQUEST	customer should contain hsid, enterpriseId or metadata	Required customer identifiers are missing	Include at least one of hsid, enterpriseId, or metadata in the customer object
Invalid Enterprise ID	INVALID_REQUEST	400 BAD REQUEST	invalid enterpriseId	Enterprise ID is not all digits	Ensure enterpriseId contains only numeric digits
Invalid HSID	INVALID_REQUEST	400 BAD REQUEST	invalid hsid	HSID is not a valid UUID	Provide a valid UUID format for the hsid
Customer Not found for given Enterprise Id	NOT_FOUND	404 NOT FOUND	Customer not found for given enterpriseId	No customer found for the provided enterpriseId	Verify the enterpriseId is correct and exists in the system
Metadata Validation
Exceeded Metadata Entries	INVALID_REQUEST	400 BAD REQUEST	Exceeded the max number of entries in metadata. Max 20	Metadata has more than 20 entries	Reduce the number of metadata entries to 20 or fewer
Metadata Key Size Exceeded	INVALID_REQUEST	400 BAD REQUEST	Metadata key size bigger than: 40	Metadata key exceeds 40 characters	Ensure all metadata keys are 40 characters or less
Metadata Value Size Exceeded	INVALID_REQUEST	400 BAD REQUEST	Metadata value size bigger than: 100	Metadata value exceeds 100 characters	Ensure all metadata values are 100 characters or less
Demographics Validation
Email Validation	INVALID_REQUEST	400 BAD REQUEST	customer.email Email should be valid	Email is not in valid format	Provide a valid email address format (e.g., user@example.com)
First Name Length Exceeded	INVALID_REQUEST	400 BAD REQUEST	First name max length is 100	First name exceeds 100 characters	Ensure the first name is 100 characters or less
Last Name Length Exceeded	INVALID_REQUEST	400 BAD REQUEST	Last name max length is 100	Last name exceeds 100 characters	Ensure the last name is 100 characters or less
SSN Validation	INVALID_REQUEST	400 BAD REQUEST	customer.ssnLastFour must match "^[0-9]4$"	SSN last four is not 4 digits	Provide exactly 4 digits for the SSN last four
ZIP Code Validation	INVALID_REQUEST	400 BAD REQUEST	Zip 5 must be exactly 5 digits long.	ZIP code is not 5 digits	Provide exactly 5 digits for the ZIP code
Date of Birth Validation	INVALID_REQUEST	400 BAD REQUEST	customer.dateOfBirth Invalid date of birth: <value>	Date of birth is not in ISO format	Use ISO 8601 format for date of birth (YYYY-MM-DD)
Country Code Validation	INVALID_REQUEST	400 BAD REQUEST	customer.phoneNumber.countryCode invalid countryCode	Country code is not valid	Use a valid country code (e.g., 01, 91)
Phone Number Validation	INVALID_REQUEST	400 BAD REQUEST	customer.phoneNumber.number invalid number	Phone number is not valid	Provide a valid phone number format

Payment Details Object Error Codes

Location

See details

Error Code Summary

Error Title Reference	Error Title	HTTP Status	Detail Message	Scenario	Resolution
Payment Details Validation
Payment Details Not Valid	INVALID_REQUEST	400 BAD REQUEST	payment details are not valid	When Qualified Amount is either missing or null	Include a valid qualified amount in the payment details
Qualified + Vision Amount Exceeds Total Amount	INVALID_REQUEST	400 BAD REQUEST	details qualified amount + vision amount cannot be greater than amount	When the sum of qualified amount and vision amount exceeds the total amount	Ensure the sum of qualified and vision amounts is less than or equal to the total amount
Prescription Amount Exceeds Qualified Amount	INVALID_REQUEST	400 BAD REQUEST	details prescription amount cannot be greater than qualified amount	When prescription amount is greater than qualified amount	Ensure prescription amount is less than or equal to qualified amount

Payment Object Error Codes

Location

See details

Error Code Summary

Error Title Reference	Error Title	HTTP Status	Detail Message	Scenario	Resolution
Payment Object Validation
Partial Authorization Not Allowed	INVALID_REQUEST	400 BAD REQUEST	Partial authorization not allowed for authorizeCard = false	When sending a request with partialAuthorization=true, authorizeCard=false, and a card included in the request	Set authorizeCard=true when using partialAuthorization=true
Statement Descriptor Suffix Invalid	INVALID_REQUEST	400 BAD REQUEST	payment.statementDescriptorSuffix only allows alphanumeric, space, hyphen and dot with at least one letter and allowed maximum length is 10	When statement descriptor suffix is invalid	Use only alphanumeric characters, spaces, hyphens, and dots in the suffix; include at least one letter; and keep it under 10 characters
Invalid Amount	INVALID_REQUEST	400 BAD REQUEST	Invalid amount ${validatedValue}, it must be between 1 and 99999999 and not contain decimals	When amount format is invalid	Ensure amount is a whole number between 1 and 99999999 and does not contain decimals
Exceeded Metadata Entries	INVALID_REQUEST	400 BAD REQUEST	Exceeded the max number of entries in metadata. Max 20	When exceeding the maximum number of metadata entries	Reduce the number of metadata entries to 20 or fewer
Metadata Key Size Exceeded	INVALID_REQUEST	400 BAD REQUEST	Metadata key size bigger than: 40	When a metadata key exceeds maximum allowed length	Ensure metadata keys are 40 characters or less
Metadata Value Size Exceeded	INVALID_REQUEST	400 BAD REQUEST	Metadata value size bigger than: 100	When a metadata value exceeds maximum allowed length	Ensure metadata values are 100 characters or less
Merchant Transaction ID Required	INVALID_REQUEST	400 BAD REQUEST	merchantTransactionId is required	When merchant transaction ID is missing in the payment object	Include a unique merchantTransactionId in the payment request
Customer Required	INVALID_REQUEST	400 BAD REQUEST	Customer is required	When customer object is missing	Include the customer object with appropriate identifiers in the request

Payment Error Codes

Location

See details

Error Code Summary

Error Title Reference	Error Title	HTTP Status	Detail Message	Scenario	Resolution
Consent Requirement	INVALID_REQUEST	400 BAD REQUEST	Consent is required!	When a ACH payment is initiated without the required consent information	Include a valid consent object with all required fields for ACH Payments
VendorPaymentMethodId Reuse	INVALID_REQUEST	400 BAD REQUEST	VendorPaymentMethodId cannot be reused.	When attempting to use a vendor payment method ID that has already been used	Use a unique vendor payment method ID that hasn't been used before
Payment Method Not Found	NOT_ACCEPTABLE	406 NOT ACCEPTABLE	Payment Method not found	When the requested payment method cannot be found in the system	Verify the payment method ID is correct and exists for the customer
Payment Method Authorization Failed	NOT_ACCEPTABLE	406 NOT ACCEPTABLE	Payment method could not be authorized. Please try a different payment method.	When the payment method cannot be authorized for the transaction	Try a different payment method or check with the customer about potential issues with their payment method
Payment Method Type Not Configured	NOT_ACCEPTABLE	406 NOT ACCEPTABLE	Payment method type is not configured.	When the payment method type is not configured for the merchant	Contact support to ensure your merchant account is configured for the payment method type you're trying to use
Payment Already Processed	INVALID_REQUEST	400 BAD REQUEST	Payment already processed or in process for given transactionId	When attempting to process a payment with merchant transaction id that is already processed or currently being processed	Use a unique merchant transaction ID for each payment request
Maximum Retries Reached	PAYMENT_ERROR	403 FORBIDDEN	Payment failed after maximum retries	When the maximum number of payment retry attempts has been reached	Create a new payment transaction or contact support for assistance
Payment Information Not Found	NOT_FOUND	404 NOT FOUND	Payment information not found.	When the requested payment information cannot be found in the system or when the payment is not associated to the merchant	Verify the payment ID is correct and belongs to your merchant account
Missing Merchant Transaction ID in GetPayment Call	INVALID_REQUEST	400 BAD REQUEST	Required query parameter 'merchantTransactionId' is not present. Please review API specs https://docs.healthsafepay.com/api-reference/	When the merchantTransactionId is missing from the request	Include the merchantTransactionId as a query parameter in your request

Stripe Payment Processing Error Codes

Location

See details

Error Code Summary

Error Title Reference	Error Title	HTTP Status	Detail Message	Scenario	Resolution
Card Authentication Errors	NOT_ACCEPTABLE	406 NOT ACCEPTABLE	This card requires an additional security step to be performed by the customer. Please have the customer enter the card via text or email; otherwise, have the customer provide a different payment method.	When card requires 3D Secure authentication in agent session	Guide the customer to complete the card entry via SMS or email where 3D Secure can be handled, or request an alternative payment method.
	NOT_ACCEPTABLE	406 NOT ACCEPTABLE	Payment method could not be authorized. This payment method requires authentication from a customer.	When card requires 3D Secure authentication in agent session	Guide the customer to complete the card entry via SMS or email where 3D Secure can be handled, or request an alternative payment method.
Card Decline Errors	NOT_ACCEPTABLE	406 NOT ACCEPTABLE	The card was declined for an unknown reason. Contact issuer for more information.	Card declined	Advise the customer to contact their card issuer to determine the reason for the decline, or use an alternative payment method.
	NOT_ACCEPTABLE	406 NOT ACCEPTABLE	An error occurred while processing the card, please try again.	Generic processing error	Attempt the transaction again. If the issue persists, request a different payment method from the customer.
	NOT_ACCEPTABLE	406 NOT ACCEPTABLE	Payment method could not be authorized. Please try a different payment method.	General payment authorization failure	Request that the customer provide an alternative payment method.
	NOT_ACCEPTABLE	406 NOT ACCEPTABLE	Payment method is canceled by a customer or expired by the financial partner	Card no longer valid	Ask the customer to update their card information or provide a new payment method.
Card Validation Errors	NOT_ACCEPTABLE	406 NOT ACCEPTABLE	The CVC number is incorrect.	Invalid CVC	Prompt the customer to re-enter the correct CVC for their card.
	NOT_ACCEPTABLE	406 NOT ACCEPTABLE	The card has expired.	Expired card	Request that the customer provide a card that has not expired.
Financial Limit Errors	NOT_ACCEPTABLE	406 NOT ACCEPTABLE	The customer's account has insufficient funds to complete the purchase. Please use an alternative payment method.	Insufficient funds error (specific to payments)	Advise the customer to use a different payment method or to fund their account before attempting the transaction again.
	NOT_ACCEPTABLE	406 NOT ACCEPTABLE	The customer has exceeded the balance, credit limit, or transaction amount limit available on their card. Contact issuer for more information.	Card limit exceeded (specific to payments)	Suggest that the customer contact their card issuer regarding their limits, or use a different payment method.
Bank Account Errors	NOT_ACCEPTABLE	406 NOT ACCEPTABLE	The customer's bank account has been closed.	Account closed	Inform the customer that the bank account has been closed and request an alternative payment method.
	NOT_ACCEPTABLE	406 NOT ACCEPTABLE	The customer's bank account could not be located.	Account not found	Verify the bank account details with the customer and correct any errors, or request an alternative payment method.
Early Warning System Errors	NOT_ACCEPTABLE	406 NOT ACCEPTABLE	earlyWarningMessage	Early warning system validation error	Review the specific early warning message and take appropriate action based on the warning type. This may require additional verification or an alternative payment method.

Refund Error Codes

Location

See details

Error Code Summary

Error Title Reference	Error Title	HTTP Status	Detail Message	Scenario	Resolution
Refund Amount Validation	INVALID_REQUEST	400 BAD REQUEST	Refund amount cannot be more than the un-refunded amount of the original payment	When attempting to refund more than the available amount	Ensure refund amount is less than or equal to the available (un-refunded) amount
	INVALID_REQUEST	400 BAD REQUEST	When paymentMethodId is present, amount is required	When using paymentMethodId without specifying an amount	Include a valid amount when using paymentMethodId
Payment Status Validation	PAYMENT_ERROR	400 BAD REQUEST	Cannot issue refund for this payment	When attempting to refund a payment not in COMPLETED status	Only attempt to refund payments that are in COMPLETED status
Payment Status Validation	INVALID_REQUEST	400 BAD REQUEST	Cannot issue refund for this payment	When attempting to refund for disputed fraudulent transaction	Disputed fraudulent transactions cannot be refunded
	INVALID_REQUEST	400 BAD REQUEST	Refunds can only be processed for captured payments	When attempting to refund a payment in AUTHORIZED status	Capture the payment before attempting to refund it or cancel the payment if not required.
	INVALID_REQUEST	400 BAD REQUEST	The amount given exceeds the allowed refund limit	When attempting to issue Credit beyond allowed refund limit	Reduce the refund amount to be within the allowed limit
Payment Identifier Validation	INVALID_REQUEST	400 BAD REQUEST	paymentId or paymentMethodId is required	When neither paymentId nor paymentMethodId is provided	Include either paymentId or paymentMethodId in the request
	INVALID_REQUEST	400 BAD REQUEST	Either paymentId or paymentMethodId should be provided. The request has both paymentId and paymentMethodId	When both paymentId and paymentMethodId are provided	Use either paymentId or paymentMethodId, not both
	INVALID_REQUEST	400 BAD REQUEST	When paymentMethodId is present, customer should contain hsid, enterpriseId or metadata	When customer identifiers are missing with paymentMethodId	Include customer identifiers when using paymentMethodId
Payment Method Status Validation	INVALID_REQUEST	400 BAD REQUEST	Payment method is canceled by a customer or expired by the financial partner	When attempting to refund using an invalid payment method	Use only valid, active payment methods for refunds
	INVALID_REQUEST	400 BAD REQUEST	Credit is not allowed for bank accounts.	When attempting to refund to a bank account payment method	Use card payment methods for unlinked refunds/credits
	INVALID_REQUEST	400 BAD REQUEST	Invalid paymentMethodId	When attempting to issue Credit for Invalid or Deleted Payment Method	Use only valid, active payment methods for refunds
Payment Dispute Validation	INVALID_REQUEST	400 BAD REQUEST	Payment is in dispute and not available for refund	When attempting to refund a payment that is in dispute	Refunds are not applicable for payments where the merchant has lost the dispute, as the customer has already received the funds through the dispute resolution process.
Refund Already Exists	INVALID_REQUEST	400 BAD REQUEST	This payment is already refunded	When attempting to create a refund on already completed payment	If the payment has already been fully refunded, additional linked refunds are not allowed. To provide more funds to the customer, issue a credit using a valid payment method.
Refund Already Exists (merchantTransactionId)	INVALID_REQUEST	400 BAD REQUEST	Refund already exists for the given merchantTransactionId	When attempting to create a refund with a duplicate merchantTransactionId	Provide a unique merchantTransactionId for every refund transaction

Checkout Session Authorization Error Codes

Location

See details

Error Code Summary

Error Title Reference	Error Title	HTTP Status	Detail Message	Scenario	Resolution
Checkout Session Authorization	FORBIDDEN	403 FORBIDDEN	Access denied when attempting to save payment method using completed session	Attempting to save payment method with a completed checkout session	Create a new session for saving payment methods; completed sessions cannot be reused
	FORBIDDEN	403 FORBIDDEN	Access denied when attempting to save payment method using PAYMENT mode	Attempting to save payment method when session is in payment mode	Use PAYMENT_METHOD_ENTRY or WALLET or PAYMENT_WITH_WALLET mode for saving payment methods
	FORBIDDEN	403 FORBIDDEN	Access denied when attempting to poll setup payment method using PAYMENT mode	Attempting to poll for setup status when session is in payment mode	Use PAYMENT_METHOD_ENTRY or WALLET or PAYMENT_WITH_WALLET mode for saving payment methods
	FORBIDDEN	403 FORBIDDEN	Access denied when attempting to save payment method using cancelled session	Attempting to save payment method with a cancelled checkout session	Create a new session; cancelled sessions cannot be reused
	FORBIDDEN	403 FORBIDDEN	Not allowed to access this session	When merchant2 tries to access a session initiated by merchant1	Use the same merchant credentials that were used to create the session

Config Object Error Codes

Location

See details

Error Code Summary

Error Title Reference	Error & Status	Detail Message	Scenario	Resolution
Config Parameter Validation
saveDisabled/paymentMethodSaveMode not supported in [modes]	INVALID_REQUEST 400 BAD REQUEST	Invalid Request. Request parameter saveDisabled or paymentMethodSaveMode not supported in Mode: [modes]	When sending a request with saveDisabled=true or paymentMethodSaveMode specified, and mode contains fallback-not-possible modes	Remove saveDisabled or paymentMethodSaveMode parameters when using non-supported modes
Payment Method ID required for PAYMENT_METHOD_DISPLAY	INVALID_REQUEST 400 BAD REQUEST	Payment Method ID is required for mode - PAYMENT_METHOD_DISPLAY	When sending a request with PAYMENT_METHOD_DISPLAY mode but omitting the payment method ID	Include a valid payment method ID when using PAYMENT_METHOD_DISPLAY mode
saveDisabled and paymentMethodSaveMode cannot be used together	INVALID_REQUEST 400 BAD REQUEST	Invalid request: 'saveDisabled' and 'paymentMethodSaveMode' cannot be used together. Use only 'paymentMethodSaveMode'.	When sending a request with both saveDisabled and paymentMethodSaveMode specified	Use only paymentMethodSaveMode parameter, not both parameters together
Merchant name contains invalid characters	INVALID_REQUEST 400 BAD REQUEST	config.merchant.name Merchant name contains invalid characters	When the merchant name in the config object contains unsupported characters (only alphanumeric, space, hyphen, and dot)	Use only alphanumeric characters, spaces, hyphens, and dots in the merchant name
Merchant name must not be blank	INVALID_REQUEST 400 BAD REQUEST	config.merchant.name Merchant name must not be blank	When the merchant name in the config object is blank or not provided	Provide a non-empty merchant name in the config object
Merchant name character limit	INVALID_REQUEST 400 BAD REQUEST	config.merchant.name Merchant name must be less than or equal to 80 characters	When the merchant name in the config object exceeds 80 characters	Ensure merchant name is 80 characters or less
Invalid mode	INVALID_REQUEST 400 BAD REQUEST	Invalid mode	When providing an invalid session mode	Use one of the supported session modes (PAYMENT, PAYMENT_WITH_WALLET, WALLET, etc.)
Invalid PaymentMethodChannel	INVALID_REQUEST 400 BAD REQUEST	Invalid PaymentMethodChannel	When providing an invalid payment method channel	Use one of the supported payment method channels
Payment method type is not configured	INVALID_REQUEST 400 BAD REQUEST	Payment method type is not configured.	Payment method type is missing or not configured for the merchant during session creation	Ensure the payment method type is configured for your merchant account
You have no capture methods available	INVALID_REQUEST 400 BAD REQUEST	You have no capture methods available.	No available channels for configured payment methods (e.g., merchant configuration or session error)	Contact support to enable appropriate capture methods for your account
config.privacyPolicyUrl must be a valid URL	INVALID_REQUEST 400 BAD REQUEST	config.privacyPolicyUrl must be a valid URL	When privacyPolicyUrl in config is not a valid URL	Provide a valid, properly formatted URL for the privacy policy
Session Mode not applicable for guest checkout	INVALID_REQUEST 400 BAD REQUEST	Session Mode not applicable for guest checkout!	When a session mode is not allowed for guest checkout (WALLET, PAYMENT_METHOD_SELECT, PAYMENT_METHOD_ENTRY, PAYMENT_WITH_WALLET)	For guest checkout, use only supported modes like PAYMENT or PAYMENT_METHOD_DISPLAY
Invalid Card Category type	INVALID_REQUEST 400 BAD REQUEST	Invalid card category type config.cardCategories.type	When a card categories type is not given as Merchant configured type ( ex: MANUFACTURER_CARD )	Use only merchant-configured card category types
More than 100 medications	INVALID_REQUEST 400 BAD REQUEST	Maximum of 100 medications allowed in cardCategories[].medication	When a card categories medication having a more than 100 medications	Limit medications to 100 per card category
Card Categories given but Medication not provided	INVALID_REQUEST 400 BAD REQUEST	Medications cannot be empty in cardCategories[].medications	When a Card Categories given as Manufacturer card, medication should have to be provided	Provide at least one medication in cardCategories[].medications
More than 100 char in cardCategories.label	INVALID_REQUEST 400 BAD REQUEST	Category label cannot exceed 100 characters	When a Card Categories label consisting more then 100 characters	Limit card category label to 100 characters or less
More than 100 char or empty string in medication.value	INVALID_REQUEST 400 BAD REQUEST	Medication value cannot be empty and maximum allowed length is 100	When a Card Categories medication label consisting more then 100 characters	Provide a non-empty medication value of 100 characters or less
More than 100 char or empty string in medication.label	INVALID_REQUEST 400 BAD REQUEST	Medication label cannot be empty and maximum allowed length is 100	When a Card Categories medication value consisting more then 100 characters	Provide a non-empty medication label of 100 characters or less

Sessions API Error Codes

Location

See details

Error Code Summary

Error Title Reference	Error Title	HTTP Status	Detail Message	Scenario	Resolution
Session Controller Validation
Card WS2 check has failed	INVALID_REQUEST	400 BAD REQUEST	Card WS2 check has failed.	WS2 verification of agent information (e.g., MSID) failed during session creation	Ensure agent userid is part of PCI_WorkStation group
Session Id not found	NOT_FOUND	404 NOT FOUND	Session Id not found	When requesting a session that doesn't exist	Check that the session ID is correct and the session has been created
Your session has been canceled	SESSION_CANCELED	410 GONE	Your session has been canceled	When requesting a canceled session	Create a new session; canceled sessions cannot be reused
Your session is no longer valid	SESSION_TIMEOUT	401 UNAUTHORIZED	Your session is no longer valid	When requesting an expired session	Create a new session; expired sessions cannot be reused
Not allowed to access this session	FORBIDDEN	403 FORBIDDEN	Not allowed to access this session	When merchant ID in request doesn't match the session's merchant ID	Use the same merchant credentials that were used to create the session
Customer Identifier is Missing	INVALID_REQUEST	400 BAD REQUEST	Customer identifier is missing	When customer identifier is not provided for session modes: PAYMENT_METHOD_ENTRY, WALLET, PAYMENT_METHOD_SELECT, PAYMENT_METHOD_DISPLAY	Include a valid customer identifier (hsid, enterpriseId, or metadata)
Consent is required	INVALID_REQUEST	400 BAD REQUEST	Consent is required!	When consent is missing in PAYMENT mode	Include a valid consent object with the required fields
payment is required	INVALID_REQUEST	400 BAD REQUEST	payment is required	When payment object is missing for session modes: PAYMENT, PAYMENT_WITH_WALLET	Include a valid payment object with the required fields