Skip to main content
Version: v2

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.

Draft version

Error Summary​

Authorization Error​

Resource Not Found Error​

Error TitleHTTP StatusError Message
NOT_FOUND404 NOT FOUNDSession Id not found

Business Rule Violation Error​

Error TitleHTTP StatusError Message
INVALID_REQUEST400 BAD REQUESTCard WS2 check has failed.
SESSION_CANCELED410 GONEYour session has been canceled
SESSION_TIMEOUT401 UNAUTHORIZEDYour session is no longer valid
FORBIDDEN403 FORBIDDENNot allowed to access this session

Schema validation error​

Error TitleHTTP StatusError Message
INVALID_REQUEST400 BAD REQUESTCustomer identifier is missing
INVALID_REQUEST400 BAD REQUESTConsent is required!
INVALID_REQUEST400 BAD REQUESTpayment is required

Config Object​

Error TitleHTTP StatusError Message
INVALID_REQUEST400 BAD REQUESTInvalid Request. Request parameter saveDisabled or paymentMethodSaveMode not supported in Mode: [modes]
INVALID_REQUEST400 BAD REQUESTPayment Method ID is required for mode - PAYMENT_METHOD_DISPLAY
INVALID_REQUEST400 BAD REQUESTInvalid request: 'saveDisabled' and 'paymentMethodSaveMode' cannot be used together. Use only 'paymentMethodSaveMode'.
INVALID_REQUEST400 BAD REQUESTconfig.merchant.name Merchant name contains invalid characters
INVALID_REQUEST400 BAD REQUESTconfig.merchant.name Merchant name must not be blank
INVALID_REQUEST400 BAD REQUESTconfig.merchant.name Merchant name must be less than or equal to 80 characters
INVALID_REQUEST400 BAD REQUESTInvalid mode
INVALID_REQUEST400 BAD REQUESTInvalid PaymentMethodChannel
INVALID_REQUEST400 BAD REQUESTPayment method type is not configured.
INVALID_REQUEST400 BAD REQUESTYou have no capture methods available.
INVALID_REQUEST400 BAD REQUESTconfig.privacyPolicyUrl must be a valid URL
INVALID_REQUEST400 BAD REQUESTSession Mode not applicable for guest checkout!
INVALID_REQUEST400 BAD REQUESTInvalid card category type config.cardCategories.type
INVALID_REQUEST400 BAD REQUESTMaximum of 100 medications allowed in cardCategories[].medication
INVALID_REQUEST400 BAD REQUESTMedications cannot be empty in cardCategories[].medications
INVALID_REQUEST400 BAD REQUESTCategory label cannot exceed 100 characters
INVALID_REQUEST400 BAD REQUESTMedication value cannot be empty and maximum allowed length is 100
INVALID_REQUEST400 BAD REQUESTMedication label cannot be empty and maximum allowed length is 100

Customer Object​

Error TitleHTTP StatusError Message
INVALID_REQUEST400customer object is required
INVALID_REQUEST400customer object must include at least one of customer.hsid, customer.enterpriseId, or customer.metadata
INVALID_REQUEST400customer.firstName cannot exceed 50 characters
INVALID_REQUEST400customer.lastName cannot exceed 50 characters
INVALID_REQUEST400customer.email must be a valid email address
INVALID_REQUEST400customer.email cannot exceed 120 characters
INVALID_REQUEST400customer.ssn must contain only digits and cannot exceed 4 characters
INVALID_REQUEST400customer.dateOfBirth must be a valid date in format YYYY-MM-DD
INVALID_REQUEST400customer.zip5 must be exactly 5 digits
INVALID_REQUEST400customer.phoneNumber.countryCode must contain only digits and must be 1 to 3 characters long
INVALID_REQUEST400customer.phoneNumber.number must contain only digits and must be 4-11 characters long
INVALID_REQUEST400customer.enterpriseIdentifier must contain only digits
INVALID_REQUEST400customer.hsid must be a valid UUID

Payment Object​

Error TitleHTTP StatusError Message
INVALID_REQUEST400paymentId must be valid UUID
INVALID_REQUEST400amount is required
INVALID_REQUEST400amount must be an integer between 1 and 99999999
INVALID_REQUEST400amount must equal the sum of paymentAllocations[:].amount
INVALID_REQUEST400merchantTransactionId is required
INVALID_REQUEST400merchantTransactionId cannot exceed 50 characters
INVALID_REQUEST400description cannot exceed 100 characters
INVALID_REQUEST400statementDescriptorSuffix only allows alphanumeric, space, hyphen and dot, and must contain at least one letter
INVALID_REQUEST400statementDescriptorSuffix cannot exceed 10 characters
INVALID_REQUEST400metadata cannot exceed 20 entries
INVALID_REQUEST400metadata key cannot exceed 40 characters
INVALID_REQUEST400metadata value cannot exceed 100 characters
INVALID_REQUEST400paymentAllocations is required and must contain at least 2 items
INVALID_REQUEST400paymentAllocations cannot contain more than 2 items
INVALID_REQUEST400paymentAllocations[n].amount is required
INVALID_REQUEST400paymentAllocations[n].amount must be an integer between 1 and 99999999
INVALID_REQUEST400paymentAllocations[n].paymentMethodId is required
INVALID_REQUEST400paymentAllocations[n].paymentMethodId must be valid UUID

Agent Object​

Payment Details Object​

Error TitleHTTP StatusError Message
UNPROCESSABLE_ENTITY422 UNPROCESSABLE ENTITYpaymentDetails.qualifiedAmount is required when paymentDetails is provided
UNPROCESSABLE_ENTITY422 UNPROCESSABLE ENTITYsum of paymentDetails.qualifiedAmount and paymentDetails.visionAmount cannot exceed amount
UNPROCESSABLE_ENTITY422 UNPROCESSABLE ENTITYpaymentDetails.prescriptionAmount cannot exceed paymentDetails.qualifiedAmount

Error Details​

Authorization Error​

Resource Not Found Error​

Business Rule Violation Error​

Schema validation error​

Config Object​

Customer Object​

Payment Object​

Agent Object​

Payment Details Object​