Version: v2

Customer Object Error Codes

This document provides a comprehensive reference for validation errors related to the customer object in the Convenient Checkout API. These errors help identify issues with customer data in API requests and guide you in resolving them.

Error Codes Summary

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

Error Codes Details

Identifier Validation

Missing Required Identifiers

Customer identifiers such as hsid, enterpriseId, or metadata are mandatory to locate the customer.

Sample Request:

{
    "customer": {
        "metadata": null,
        "hsid": null,
        "enterpriseId": null
    }
}

Sample Response:

{
    "title": "INVALID_REQUEST",
    "status": 400,
    "detail": "customer should contain hsid, enterpriseId or metadata"
}

Invalid hsid

Validates that the HSID is a properly formatted UUID.

Sample Request:

{
  "email": "test@example.com",
  "hsid": "invalid-hsid"
}

Sample Response:

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "invalid hsid"
}

Invalid enterpriseId

Validates that Enterprise ID contains only digits.

Sample Request:

{
  "email": "test@example.com",
  "enterpriseId": "abc123"
}

Sample Response:

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "invalid enterpriseId"
}

Customer Not found for given Enterprise Id

Returned when no customer is found for the provided enterpriseId.

Sample Request:

{
  "enterpriseId": "9999999999"
}

Sample Response:

{
  "title": "NOT_FOUND",
  "status": 404,
  "detail": "Customer not found for given enterpriseId"
}

Metadata Validation

Exceeded Metadata Entries

Maximum 20 entries allowed in metadata.

Sample Request:

{
  "email": "test@example.com",
  "metadata": {
    "key1": "value1",
    "key2": "value2"
    // ... 19 more key-value pairs ...
  }
}

Sample Response:

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "Exceeded the max number of entries in metadata. Max 20"
}

Metadata Key Size Exceeded

Maximum 40 characters for metadata key.

Sample Request:

{
  "email": "test@example.com",
  "metadata": {
    "thisKeyIsVeryLongAndExceedsTheMaximumAllowedLengthForMetadataKeys": "value"
  }
}

Sample Response:

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "Metadata key size bigger than: 40"
}

Metadata Value Size Exceeded

Maximum 100 characters for metadata value.

Sample Request:

{
  "email": "test@example.com",
  "metadata": {
    "key": "This value is too long and exceeds the maximum allowed length for metadata values which is 100 characters according to the validation rules defined in the system."
  }
}

Sample Response:

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "Metadata value size bigger than: 100"
}

Demographics Validation

Email Validation

Validates that the email is properly formatted according to email standards.

Sample Request:

{
  "email": "invalid-email",
  "hsid": "123e4567-e89b-12d3-a456-426614174000"
}

Sample Response:

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "customer.email Email should be valid"
}

First Name Length Exceeded

First name has a maximum length validation (100 characters).

Sample Request:

{
  "firstName": "A very long first name that exceeds the maximum allowed length of 100 characters..."
}

Sample Response:

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "First name max length is 100"
}

Last Name Length Exceeded

Last name has a maximum length validation (100 characters).

Sample Request:

{
  "lastName": "A very long last name that exceeds the maximum allowed length of 100 characters..."
}

Sample Response:

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "Last name max length is 100"
}

SSN Validation

SSN last four digits must be exactly 4 numeric digits.

Sample Request:

{
  "email": "test@example.com",
  "ssnLastFour": "123"
}

Sample Response:

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "customer.ssnLastFour must match "^[0-9]{4}$""
}

ZIP Code Validation

ZIP code must be exactly 5 digits.

Sample Request:

{
  "email": "test@example.com",
  "zip5": "1234"
}

Sample Response:

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "Zip 5 must be exactly 5 digits long."
}

Date of Birth Validation

Date of birth must be in ISO date format (YYYY-MM-DD).

Sample Request:

{
  "email": "test@example.com",
  "dateOfBirth": "01-01-2000"
}

Sample Response:

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "customer.dateOfBirth Invalid date of birth: 01-01-2000"
}

Phone Number Validation

Validates phone number components for proper formatting.

Sample Request (Invalid Country Code):

{
  "email": "test@example.com",
  "phoneNumber": {
    "countryCode": "ABC",
    "number": "1234567890"
  }
}

Sample Response:

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "customer.phoneNumber.countryCode invalid countryCode"
}

Sample Request (Invalid Number):

{
  "email": "test@example.com",
  "phoneNumber": {
    "countryCode": "01",
    "number": "123"
  }
}

Sample Response:

{
  "title": "INVALID_REQUEST",
  "status": 400,
  "detail": "customer.phoneNumber.number invalid number"
}

Error Codes Summary​

Error Codes Details​

Identifier Validation​

Metadata Validation​

Demographics Validation​

Error Codes Summary

Error Codes Details

Identifier Validation

Metadata Validation

Demographics Validation