Error codes

The HLC API returns structured error codes with descriptive messages to facilitate debugging and error handling. Use these codes to implement user-friendly error messages and automated retry logic.

Error Code Categories

Error codes are prefixed by category:

SYS: System and authentication errors
ACC: Account and user management errors
ORD: Order processing and fulfillment errors
PMT: Payment and transaction errors
CAT: Catalog and product errors
SERV: Order creation and validation errors
CUST: Customer account errors
SHIP: Shipping address and delivery errors
PAYM: Payment and credit card errors
ORDR: Order line item errors
PROD: Product and variant errors
CREA: Order creation process errors

Error Code Reference

System Errors

Code	Meaning
SYS0001	Invalid Token

Account Errors

Code	Meaning
ACC0001	Request must contain at least one label
ACC0002	No content found
ACC0003	Invalid items in label update: `{0}`
ACC0004	No invoice found
ACC0005	Invoice number is mandatory

Order Errors

Code	Meaning
ORD0001	`dateFrom` must be prior or equal to `dateTo`
ORD0002	Sales orders creation disabled
ORD0003	Doorstep Delivery access not granted
ORD0004	Error during cart creation
ORD0005	Delivery address is not valid
ORD0006	ReturnAddressID is not valid
ORD0007	Document language must be `en` or `fr`
ORD0008	Product identifier cannot be resolved
ORD0009	Product defined multiple times
ORD0010	Not enough inventory available
ORD0011	No content found
ORD0012	Product not allowed for doorstep delivery
ORD0013	Request must contain items
ORD0014	Doorstep delivery payment preferences not set
ORD0015	Call customer service to order product
ORD0016	Items with missing quantities: `{0}`
ORD0017	Order number is mandatory for tracking
ORD0018	No tracking number found or not available yet
ORD0019	Authorized dealers only for product `{0}`
ORD0020	PO box addresses are not supported
ORD0021	PurchaseOrderNumber is required and it must not exceed 60 characters
ORD0022	Payload is not valid
ORD0023	If a warehouse is provided, a delivery mode and a carrier account number are required
ORD0024	Both carrier number and delivery mode are required if either is provided
ORD0025	Delivery mode is not valid
ORD0099	Order identifier is mandatory
ORD0500	Unexpected validation error, contact HLC support

Payment Errors

Code	Meaning
PMT0001	Transaction declined – try a different card
PMT0002	Billing address verification failed
PMT0003	Transaction declined – try a different card
PMT0004	Invalid expiration date
PMT0005	Withdrawal limit reached
PMT0006	Insufficient funds
PMT0007	Invalid security code
PMT0008	Invalid account number
PMT0009	Error – contact customer service
PMT0010	Transaction declined – contact card provider
PMT0011	Request declined – try again

Catalog Errors

Code	Meaning
CAT0001	Invalid product status
CAT0002	No content found

Order Creation Errors

Code	Meaning
SERV0001	Order cannot be created because pricing settings are invalid. Either line pricing has to be set, or `MustRetrieveLinePricing` setting must be set to `true`
SERV0002	Order cannot be created because the reference number is not set
SERV0003	Order cannot be created because the reference number is not unique in the request
SERV0004	Order cannot be created because the pool is invalid
SERV0005	Order cannot be created because the order type is invalid
SERV0006	`AllowPartialDelivery` cannot be set to `true` yet

Customer Errors

Code	Meaning
CUST1001	Order cannot be retrieved because the account number is not specified
CUST1002	Order cannot be created because the purchase order number is missing
CUST1003	Order cannot be created because the customer doesn't have the right to order via the doorstep program
CUST1006	Customer does not have any API configurations
CUST1007	Customer requires a carrier account number

Shipping Errors

Code	Meaning
SHIP2001	Order cannot be created because the shipping address is not specified
SHIP2002	Order cannot be created because the warehouse is not set for some lines and `MustUseDCHierachiesToRetrieveWarehouse` is set to `false`
SHIP2003	Order cannot be created because the delivery mode is not set for one or more lines and `MustFreightShop` is set to `false`
SHIP2004	Order cannot be created because freight shopper could not find rates
SHIP2005	Order cannot be created because the shipping address has an invalid state
SHIP2006	Order cannot be created because the shipping address has an invalid country
SHIP2007	Order cannot be created because the address is invalid
SHIP2008	An error occur during the address validation (`{0}`)
SHIP2009	Order cannot be created because the shipping country must be the same as the company's country

Payment Errors (PAYM)

Code	Meaning
PAYM3001	Credit card profile ID is not set up correctly
PAYM3002	Order cannot be processed because one of the payment information is incorrect
PAYM3003	Credit card or ACH profile ID is missing
PAYM3004	Card authorization failed
PAYM3005	ACH Payment validation failed

Order Line Item Errors

Code	Meaning
ORDR4001	Item restricted
ORDR4002	Order cannot be created because the following items cannot be sold via the doorstep program
ORDR4003	Order cannot be created because the following items are now discontinued

Product Errors (PROD)

Code	Meaning
PROD5001	The following variants do not exist

Order Creation Process Errors

Code	Meaning
CREA9001	Order cannot be created because the creation process failed post-validations
CREA9002	Pool not set
CREA9003	Order cannot be created because freight shopper couldn't find rates
CREA9004	Order cannot be created because an error happened while getting the freight and handling charges
CREA9005	Not enough inventory to fulfill order

Implementation Example

Client-Side Error Mapping

const errorMessages = {
  SYS0001:
    'Your API key is invalid or has expired. Please check your credentials.',
  ORD0010:
    'Insufficient inventory available. Please reduce quantity or try again later.',
  PMT0001: 'Payment declined. Please try a different payment method.',
  PMT0006: 'Insufficient funds. Please use a different payment method.',
  ORD0003: 'Doorstep delivery is not available for your account.',
}

function getUserMessage(errorCode) {
  return (
    errorMessages[errorCode] ??
    'An unexpected error occurred. Please try again or contact support.'
  )
}

// Usage in error handling
try {
  const response = await fetch(`${apiUrl}/Orders/Create/Fulfillment`, {
    method: 'POST',
    headers: {
      Authorization: `ApiKey ${apiKey}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(orderData),
  })

  if (!response.ok) {
    const error = await response.json()
    throw new Error(getUserMessage(error.code))
  }

  const order = await response.json()
} catch (error) {
  console.error('Order creation failed:', error.message)
  // Display error.message to user
}