--- title: Error Code Glossary slug: devdocs/error-code-glossary docTags: createdAt: 2026-10-16T12:03:52.300Z --- ## Where an error appears An operation can fail in three places. Check all of them. | Place | When | HTTP status | | ---------------------------- | ----------------------------------------------------------- | ----------- | | The HTTP status | Authentication or routing problem | 401, 404 | | The top-level `errors` array | The query is invalid: unknown field, wrong type, bad syntax | 200 | | The mutation result | A business rule failed | 200 | ## HTTP status codes | Status | Meaning | Fix | | ------- | -------------------------------------------------- | ------------------------------------------------------ | | **401** | The Bearer token is missing, expired or malformed. | Get a new token. Send `Authorization: Bearer `. | | **404** | You sent a `GET` request to the GraphQL endpoint. | Use `POST`. | ## Mutation errors Every mutation returns the same wrapper, in both APIs. ```json { "data": { "customer": { "create": { "result": null, "errorCode": 2, "errorMessage": "Invalid Customer Category", "errorData": null } } } } ``` | Field | Description | | -------------- | ------------------------------------------------------------- | | `errorCode` | A number. `null` when the operation succeeds. | | `errorMessage` | The name of the error, split in words. | | `errorData` | Details, for example the list of the keys that were rejected. | :::BlockQuote ℹ️ **INFO** When `errorCode` is returned, the operation was not done. For example, when **Add Order** returns an `errorCode`, the order was not created. ::: ## Read the catalogue from the API The `errorCodes` query returns every code, with its name and its meaning. **Query** ```graphql query GetErrorCodes { errorCodes { deliveryOrder { code name description } customer { code name description } organization { code name description } } } ``` **cURL** ```bash curl --location 'https://sandbox.expressoft.eu/connect/api/interopgql' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ' \ --data '{"query": "query GetErrorCodes { errorCodes { deliveryOrder { code name description } customer { code name description } organization { code name description } } }"}' ``` **Response** ```json { "data": { "errorCodes": { "customer": [ { "code": 1, "name": "InvalidCustomer", "description": "The customer key does not identify an active customer." } ], "organization": [ { "code": 13, "name": "GiftCardDuplicateCode", "description": "An active, unused gift card with the same code already exists." } ] } } } ``` ## Error codes ### Add Order (`deliveryOrder.*`) | `errorCode` | Name | When it is returned | | ----------- | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | `InvalidLocation` | locationKey and callCenterKey are both missing, or locationKey is not an active delivery location. errorData is empty; errorMessage may contain details. | | 2 | `InvalidCallCenter` | callCenterKey is not an active location, or the location is not configured as a call center. errorData is empty; errorMessage may contain details. | | 3 | `InvalidCustomer` | customerKey does not identify an active customer. errorData is empty. | | 4 | `InvalidCustomerAddress` | customerAddressKey does not identify an active address (CustomerAddressType.active = true) of the customer given in customerKey. Check the address with customers.customer.addresses(publicKey) before ordering; if it is inactive, create a new one with customer.createAddress and use the returned publicKey. errorData is empty. | | 5 | `InvalidCustomerPaymentMethods` | One or more payments\[].paymentKey values do not identify an active payment method. errorData: list of the rejected paymentKey values. | | 6 | `InvalidTicketPayment` | A meal ticket payment was sent without ticketPayments details. errorData: list of the affected paymentKey values. | | 7 | `InvalidTicketPaymentProvider` | One or more payments\[].ticketPayments\[].companyKey values do not identify an active meal ticket provider. errorData: list of the rejected companyKey values. | | 8 | `InvalidInvoiceCustomer` | invoice.clientType is Customer and invoice.clientKey does not identify an active customer. errorData: list with the rejected key. | | 9 | `InvalidInvoiceCustomerAddress` | invoice.clientType is Customer and invoice.clientAddressKey does not identify an active customer address. errorData: list with the rejected key. | | 10 | `InvalidInvoiceCompany` | invoice.clientType is Company and invoice.clientKey does not identify an active company. errorData: list with the rejected key. | | 11 | `InvalidInvoiceCompanyAddress` | invoice.clientType is Company and invoice.clientAddressKey does not identify an active company address. errorData: list with the rejected key. | | 12 | `ProductValidationError` | The ordered products could not be validated because of a temporary internal error; this is not caused by the payload. The order was NOT created and it is safe to send it again. errorData: short error message(s). | | 13 | `InvalidProduct` | orders\[].productKey (or a bundle option product that has addons) is not available for the given salePriceCategoryKey: the product is inactive or has no active price in that sale price category. A product valid for one sale price category can be invalid for another; build the menu with products(salePriceCategory: ). errorData: the rejected productKey.
| | 14 | `NoTaxDefinedOnOrderProduct` | orders\[].productKey has no tax (VAT) defined. errorData: the affected productKey. | | 15 | `InvalidPromotion` | orders\[].promotionKey or subtotalDiscount.promotionKey does not identify an active promotion. errorData: list of the rejected promotion keys. | | 16 | `InvalidOrderAddonVariantProduct` | orders\[].addon.variants\[] contains a variantKey / productKey pair not defined in the addons.variants of the ordered product (see products(...).addons). errorData: \{ product, variant }. | | 17 | `NoTaxDefinedOnOrderAddonVariantProduct` | The addon variant product has no tax (VAT) defined. errorData: \{ product, variant }. | | 18 | `InvalidOrderAddonOptionProduct` | orders\[].addon.options\[].productKey is not defined in the addons.options of the ordered product (see products(...).addons). errorData: \{ product, option }. | | 19 | `NoTaxDefinedOnOrderAddonOptionProduct` | The addon option product has no tax (VAT) defined. errorData: \{ product, option }. | | 20 | `InvalidOrderBundleOptionProduct` | orders\[].bundle.options\[] contains an optionIndex / productKey pair not defined in the bundle.options of the ordered product (see products(...).bundle). errorData: \{ product, option }. | | 21 | `NoTaxDefinedOnOrderBundleOptionProduct` | The bundle option product has no tax (VAT) defined. errorData: \{ product, option }. | | 22 | `NoOrders` | orders is empty, or every line has quantity 0 (lines with quantity 0 are ignored). errorData is empty. | | 23 | `InvalidLocationDeliveryProfile` | The delivery location (locationKey) has no active delivery profile / delivery area configured (or its delivery area has no server group), or the account has no delivery area at all. errorData is empty; errorMessage may contain details. | | 24 | `UnavailableLocation` | The delivery location (locationKey) is currently marked as unavailable for delivery orders. Retry later or choose another location. errorData is empty. | | 25 | `NoTaxDefinedOnDeliveryFee` | deliveryFee was sent but no tax (VAT) is configured for the delivery fee. errorData is empty. | | 26 | `SubtotalDiscountExceedUndiscountedAmount` | subtotalDiscount.value exceeds the amount eligible to be discounted. errorData: \{ eligibleToBeDiscounted }. | | 27 | `UnbalancedAmounts` | Checked only when payments are sent: the sum of payments\[].paymentAmount differs from the order total. Order total = sum of orders\[] lines ((salePrice + packaging.salePrice) \* quantity + discountAmount, plus bundle options and addons) + deliveryFee + serviceChargeFee + subtotalDiscount.value; discounts are negative values, amounts are rounded to 2 decimals. errorData: \{ ordersAmount, paidAmount }. | | 28 | `ForbiddenChannelType` | channelType is not a trusted channel configured for the account. errorData is empty. | | 29 | `NoProductPackagingDefined` | packaging was sent for a product that has no packaging defined (see products(...).packaging). errorMessage: product name. | | 30 | `NoTaxDefinedOnProductPackaging` | The packaging product has no tax (VAT) defined. errorMessage: product name. | | 31 | `OrderDiscountExceedUndiscountedAmount` | orders\[].discountAmount (absolute value) exceeds salePrice \* quantity of that line. errorData: the affected productKey. | | 32 | `ForbiddenNegativeOrderQuantity` | orders\[] contains a line with negative quantity. errorData is empty. | | 33 | `DuplicateKey` | An order with the given key (DeliveryOrderCreateInputType.key) already exists; the order was not created again. errorData is empty. | | 34 | `ValidationTimeout` | The order could not be validated within the time limit because of a temporary slowness; this is not caused by the payload. The order was NOT created and it is safe to send it again (with the same key). errorData is empty. | ### Customer mutations (`customer.*`) | `errorCode` | Name | When it is returned | | ----------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | `InvalidCustomer` | The customer key (publicKey / customerKey) does not identify an active customer. For marketing actions errorData: list of the rejected customerKey values; otherwise errorData is empty. | | 2 | `InvalidCustomerCategory` | category does not identify an active customer category. errorData is empty. | | 3 | `InvalidStreet` | streetKey does not identify an active street. errorData is empty. | | 4 | `InvalidEmailFormat` | email is not a valid email address. errorData is empty. | | 5 | `InvalidCustomerAddress` | The address publicKey does not identify an existing active address (CustomerAddressType.active = true). An inactive address cannot be updated or deleted; create a new one with customer.createAddress and use the returned publicKey. errorData is empty. | | 6 | `InvalidCompany` | companyKey does not identify an active company. errorData is empty. | | 7 | `InvalidMarketingAction` | marketingActionKey does not identify an active marketing action. errorData: list of the rejected marketingActionKey values. | ### Organization mutations (`organization.*`) | `errorCode` | Name | When it is returned | | ----------- | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | `InvalidCity` | cityKey is missing or does not identify an existing city. errorData is empty. | | 2 | `InvalidDistrict` | districtKey does not identify a district of the given city. errorData is empty. | | 3 | `InvalidStreet` | Street create: name is empty. Street update: publicKey does not identify an existing active street. Location street upsert: one or more items\[].streetKey values are not active streets (errorData: list of the rejected keys). | | 4 | `InvalidStreetName` | Street update: name is empty. errorData is empty. | | 5 | `LocationAreaStreetDuplicate` | items contains the same deliveryAreaKey / locationKey / streetKey combination more than once. errorData: list of the duplicated combinations. | | 6 | `InvalidDeliveryArea` | One or more items\[].deliveryAreaKey values do not identify an active delivery area. errorData: list of the rejected keys. | | 7 | `InvalidLocation` | One or more items\[].locationKey values do not identify an active location. errorData: list of the rejected keys. | | 8 | `CompanyWithSameFiscalCodeConflict` | Another active company with the same fiscalCode already exists. errorData is empty. | | 9 | `InvalidCompanyCategory` | category does not identify an active company category. errorData is empty. | | 10 | `InvalidCompany` | The company key (publicKey / companyKey) does not identify an active company. errorData is empty. | | 11 | `InvalidCompanyAddress` | The company address publicKey does not identify an existing active company address. errorData is empty. | | 12 | `InvalidCounty` | countyKey does not identify an existing county. errorData is empty. | | 13 | `GiftCardDuplicateCode` | An active, unused gift card with the same code already exists for the organization in an overlapping startOn / expireOn period, or a unique code could not be generated. errorData is empty. | | 14 | `InvalidOrganization` | organizationKey does not identify an active organization. errorData is empty. | | 15 | `InvalidVATCategory` | vatCategoryKey does not identify an existing VAT category. errorData is empty. | | 16 | `InvalidCurrency` | currencyKey does not identify an existing currency. errorData is empty. | ## Authentication errors The token request returns `errorCode` and `errorMessage` in its response body. Both are `null` when authentication succeeds. ## Webhook delivery failures (Delivery API only) When your callback endpoint doesn't return a 2xx status, Expressoft retries two more times, 5 seconds apart. Then it stops.