Session API Error Codes
This page documents all error codes for the Sessions API (v2). These errors occur when creating and managing checkout sessions. Each error includes the code name, HTTP status, description, recommended developer action, and notes where applicable.
Error Summary
Authorization Error
| Error Title | HTTP Status | Error Message |
|---|---|---|
| FORBIDDEN | 403 | Access denied when attempting to save payment method using completed session |
| FORBIDDEN | 403 | Access denied when attempting to save payment method using PAYMENT mode |
| FORBIDDEN | 403 | Access denied when attempting to poll setup payment method using PAYMENT mode |
| FORBIDDEN | 403 | Access denied when attempting to save payment method using cancelled session |
| FORBIDDEN | 403 | Not allowed to access this session |
| FORBIDDEN | 403 | Invalid access token for the given merchantId |
| FORBIDDEN | 403 | Not allowed to access this session |
| SESSION_CANCELED | 410 | Your session has been canceled |
| SESSION_TIMEOUT | 401 | Your session is no longer valid |
Resource Not Found Error
| Error Title | HTTP Status | Error Message |
|---|---|---|
| NOT_FOUND | 404 | Session Id not found |
| NOT_FOUND | 404 | Parent Session id is invalid |
Business Rule Violation Error
| Error Title | HTTP Status | Error Message |
|---|---|---|
| UNPROCESSABLE_ENTITY | 422 | Card WS2 check has failed |
| UNPROCESSABLE_ENTITY | 422 | consent is required |
| UNPROCESSABLE_ENTITY | 422 | payment is required |
| UNPROCESSABLE_ENTITY | 422 | Payment method type is not configured |
| UNPROCESSABLE_ENTITY | 422 | Partial authorization not allowed for authorizeCard = false |
Config Object
| Error Title | HTTP Status | Error Message |
|---|---|---|
| UNPROCESSABLE_ENTITY | 422 | Invalid Request. Request parameter saveDisabled or paymentMethodSaveMode not supported in Mode: [modes] |
| UNPROCESSABLE_ENTITY | 422 | Payment Method ID is required for mode - PAYMENT_METHOD_DISPLAY |
| UNPROCESSABLE_ENTITY | 422 | Invalid request: 'saveDisabled' and 'paymentMethodSaveMode' cannot be used together. Use only 'paymentMethodSaveMode' |
| UNPROCESSABLE_ENTITY | 422 | Payment method type is not configured |
| UNPROCESSABLE_ENTITY | 422 | You have no capture methods available |
| UNPROCESSABLE_ENTITY | 422 | Medication list contains duplicate items |
| UNPROCESSABLE_ENTITY | 422 | UI version '%s' is not supported for backend API version '%s'. Supported versions: %s |
Customer Object
| Error Title | HTTP Status | Error Message |
|---|---|---|
| UNPROCESSABLE_ENTITY | 422 | customer object is required |
| UNPROCESSABLE_ENTITY | 422 | customer object must include at least one of customer.hsid, customer.enterpriseId, or customer.metadata |
Consent Object
| Error Title | HTTP Status | Error Message |
|---|---|---|
| UNPROCESSABLE_ENTITY | 422 | agent is required when Collection Type is TEL or PPD |
Payment Details Object
| Error Title | HTTP Status | Error Message |
|---|---|---|
| UNPROCESSABLE_ENTITY | 422 | paymentDetails.qualifiedAmount is required when paymentDetails is provided |
| UNPROCESSABLE_ENTITY | 422 | sum of paymentDetails.qualifiedAmount and paymentDetails.visionAmount cannot exceed amount |
| UNPROCESSABLE_ENTITY | 422 | paymentDetails.prescriptionAmount cannot exceed paymentDetails.qualifiedAmount |
Schema validation error
Config Object
| Error Title | HTTP Status | Error Message |
|---|---|---|
| INVALID_REQUEST | 400 | config.merchant.name contains invalid characters |
| INVALID_REQUEST | 400 | config.merchant.name must not be blank |
| INVALID_REQUEST | 400 | config.merchant.name must be less than or equal to 80 characters |
| INVALID_REQUEST | 400 | Invalid mode |
| INVALID_REQUEST | 400 | Invalid PaymentMethodChannel |
| INVALID_REQUEST | 400 | config.privacyPolicyUrl must be a valid URL |
| INVALID_REQUEST | 400 | Maximum of 100 medications allowed in cardCategories[].medication |
| INVALID_REQUEST | 400 | Medications cannot be empty in cardCategories[].medications |
| INVALID_REQUEST | 400 | Category label cannot exceed 100 characters |
| INVALID_REQUEST | 400 | config.cardCategories.type is invalid |
| INVALID_REQUEST | 400 | Medication value cannot be empty and maximum allowed length is 100 |
| INVALID_REQUEST | 400 | Medication label cannot be empty and maximum allowed length is 100 |
| INVALID_REQUEST | 400 | config.uiVersion must be in valid format |
Customer Object
| Error Title | HTTP Status | Error Message |
|---|---|---|
| INVALID_REQUEST | 400 | customer.firstName cannot exceed 50 characters |
| INVALID_REQUEST | 400 | customer.lastName cannot exceed 50 characters |
| INVALID_REQUEST | 400 | customer.email must be a valid email address |
| INVALID_REQUEST | 400 | customer.email cannot exceed 120 characters |
| INVALID_REQUEST | 400 | customer.ssn must contain only digits and cannot exceed 4 characters |
| INVALID_REQUEST | 400 | customer.dateOfBirth must be a valid date in format YYYY-MM-DD |
| INVALID_REQUEST | 400 | customer.zip5 must be exactly 5 digits |
| INVALID_REQUEST | 400 | customer.phoneNumber.countryCode must contain only digits and must be 1 to 3 characters long |
| INVALID_REQUEST | 400 | customer.phoneNumber.number must contain only digits and must be 4-11 characters long |
| INVALID_REQUEST | 400 | customer.enterpriseIdentifier must contain only digits |
| INVALID_REQUEST | 400 | customer.hsid must be a valid UUID |
Payment Object
| Error Title | HTTP Status | Error Message |
|---|---|---|
| INVALID_REQUEST | 400 | payment.amount is required |
| INVALID_REQUEST | 400 | payment.amount must be an integer between 1 and 99999999 |
| INVALID_REQUEST | 400 | payment.merchantTransactionId is required |
| INVALID_REQUEST | 400 | payment.merchantTransactionId cannot exceed 50 characters |
| INVALID_REQUEST | 400 | payment.description cannot exceed 100 characters |
| INVALID_REQUEST | 400 | payment.statementDescriptorSuffix only allows alphanumeric, space, hyphen and dot, and must contain at least one letter |
| INVALID_REQUEST | 400 | payment.statementDescriptorSuffix cannot exceed 10 characters |
| INVALID_REQUEST | 400 | payment.metadata cannot exceed 20 entries |
| INVALID_REQUEST | 400 | payment.metadata key cannot exceed 40 characters |
| INVALID_REQUEST | 400 | payment.metadata value cannot exceed 100 characters |
Agent Object
| Error Title | HTTP Status | Error Message |
|---|---|---|
| INVALID_REQUEST | 400 | agent.userId is required |
| INVALID_REQUEST | 400 | agent.userId cannot exceed 50 characters |
| INVALID_REQUEST | 400 | agent.firstName cannot exceed 50 characters |
| INVALID_REQUEST | 400 | agent.lastName cannot exceed 50 characters |
Consent Object
| Error Title | HTTP Status | Error Message |
|---|---|---|
| INVALID_REQUEST | 400 | payment.consent.merchantConsentText is required |
| INVALID_REQUEST | 400 | payment.consent.merchantConsentText cannot exceed 1000 characters |
| INVALID_REQUEST | 400 | payment.consent.merchantConsentId is required |
| INVALID_REQUEST | 400 | payment.consent.merchantConsentId cannot exceed 100 characters |
| INVALID_REQUEST | 400 | payment.consent.consentCollectionTimestamp is required |
| INVALID_REQUEST | 400 | payment.consent.consentCollectionTimestamp must be in ISO 8601 format |
| INVALID_REQUEST | 400 | Country Code for Telephone Consent must contain only digits and must be 1 to 3 characters long |
| INVALID_REQUEST | 400 | PhoneNumber for Telephone Consent must contain only digits and must be 4-11 characters long |
| INVALID_REQUEST | 400 | ConsentCollectionType should match any one of the values accepted for Enum class: [TEL, WEB, PPD] |
Error Details
Authorization Error
Access denied when attempting to save payment method using completed session403
Access denied when attempting to save payment method using PAYMENT mode403
Access denied when attempting to poll setup payment method using PAYMENT mode403
Access denied when attempting to save payment method using cancelled session403
Not allowed to access this session403
Invalid access token for the given merchantId403
Not allowed to access this session403
Your session has been canceled410
Your session is no longer valid401
Resource Not Found Error
Session Id not found404
Parent Session id is invalid404
Business Rule Violation Error
Card WS2 check has failed422
consent is required422
payment is required422
Payment method type is not configured422
Partial authorization not allowed for authorizeCard = false422
Config Object
Invalid Request. Request parameter saveDisabled or paymentMethodSaveMode not supported in Mode: [modes]422
Payment Method ID is required for mode - PAYMENT_METHOD_DISPLAY422
Invalid request: 'saveDisabled' and 'paymentMethodSaveMode' cannot be used together. Use only 'paymentMethodSaveMode'422
Payment method type is not configured422
You have no capture methods available422
Medication list contains duplicate items422
UI version '%s' is not supported for backend API version '%s'. Supported versions: %s422
Customer Object
customer object is required422
customer object must include at least one of customer.hsid, customer.enterpriseId, or customer.metadata422
Consent Object
agent is required when Collection Type is TEL or PPD422
Payment Details Object
paymentDetails.qualifiedAmount is required when paymentDetails is provided422
sum of paymentDetails.qualifiedAmount and paymentDetails.visionAmount cannot exceed amount422
paymentDetails.prescriptionAmount cannot exceed paymentDetails.qualifiedAmount422
Schema validation error
Config Object
config.merchant.name contains invalid characters400
config.merchant.name must not be blank400
config.merchant.name must be less than or equal to 80 characters400
Invalid mode400
Invalid PaymentMethodChannel400
config.privacyPolicyUrl must be a valid URL400
Maximum of 100 medications allowed in cardCategories[].medication400
Medications cannot be empty in cardCategories[].medications400
Category label cannot exceed 100 characters400
config.cardCategories.type is invalid400
Medication value cannot be empty and maximum allowed length is 100400
Medication label cannot be empty and maximum allowed length is 100400
config.uiVersion must be in valid format400
Customer Object
customer.firstName cannot exceed 50 characters400
customer.lastName cannot exceed 50 characters400
customer.email must be a valid email address400
customer.email cannot exceed 120 characters400
customer.ssn must contain only digits and cannot exceed 4 characters400
customer.dateOfBirth must be a valid date in format YYYY-MM-DD400
customer.zip5 must be exactly 5 digits400
customer.phoneNumber.countryCode must contain only digits and must be 1 to 3 characters long400
customer.phoneNumber.number must contain only digits and must be 4-11 characters long400
customer.enterpriseIdentifier must contain only digits400
customer.hsid must be a valid UUID400
Payment Object
payment.amount is required400
payment.amount must be an integer between 1 and 99999999400
payment.merchantTransactionId is required400
payment.merchantTransactionId cannot exceed 50 characters400
payment.description cannot exceed 100 characters400
payment.statementDescriptorSuffix only allows alphanumeric, space, hyphen and dot, and must contain at least one letter400
payment.statementDescriptorSuffix cannot exceed 10 characters400
payment.metadata cannot exceed 20 entries400
payment.metadata key cannot exceed 40 characters400
payment.metadata value cannot exceed 100 characters400
Agent Object
agent.userId is required400
agent.userId cannot exceed 50 characters400
agent.firstName cannot exceed 50 characters400
agent.lastName cannot exceed 50 characters400
Consent Object
payment.consent.merchantConsentText is required400
payment.consent.merchantConsentText cannot exceed 1000 characters400
payment.consent.merchantConsentId is required400
payment.consent.merchantConsentId cannot exceed 100 characters400
payment.consent.consentCollectionTimestamp is required400
payment.consent.consentCollectionTimestamp must be in ISO 8601 format400
Country Code for Telephone Consent must contain only digits and must be 1 to 3 characters long400
PhoneNumber for Telephone Consent must contain only digits and must be 4-11 characters long400
ConsentCollectionType should match any one of the values accepted for Enum class: [TEL, WEB, PPD]400