Skip to main content

Menu Errors & Warnings

For: Developers.

Menu creation returns three classes of feedback: submission errors that reject the request outright, runtime errors that stop the menu from being created, and runtime warnings that allow creation but flag deficiencies. Each type below lists what triggers it, an example response, and how to resolve it.

Submission Errors

These errors are returned immediately to the API User, and prevent a Menu Creation Request from being created.

Required Fields

Fields that cannot be blank/null:

  • location_id (UUID format required)

  • pos_id (string)

  • name (string)

  • start_date (date format, cannot be blank)

  • categories (array, minimum 1 required)

  • items (array, minimum 1 required)

Example responses

{"errors": [
  ...
  Field \"locationId\" of required type \"UUID!\" was not provided.",
  ...]}
{"errors": [
  ...
  message": "Variable $menu of type MenuInput! was provided invalid value for locationId (\"\" is not a valid UUID)",
  ...]}

Recommended actions

  • Ensure all required fields are provided

  • Verify UUID format for location_id

  • Use proper date format for start_date

Collection Length

  • Categories and items arrays must have at least 1 element

  • Item selections must have 1-5 elements

  • Choice selections must have 1-5 elements

Example responses

{"errors": [
  ...
  "message": "items is too short (minimum is 1)",
  ...]}

{"errors": [
  ...
  "message": "selections is too short (minimum is 1)",
  ...]}

Recommended actions

  • Provide at least one category and one item

  • Ensure each item has 1-5 selections

  • Ensure each choice has 1-5 selections

Item Type Tag

Specific business rule validation - this tag can only be applied to choices.

Example response

{"errors": [
  ...
  "message": "The 'individuallyPackagedRelishSide' tag is only valid for choices, not for items",
  ...]}

Recommended actions

  • Remove individuallyPackagedRelishSide from item item_type_tags

  • Apply this tag to appropriate choices instead

Runtime Errors

These errors are aggregated throughout the course of the Menu Creation, and are returned when the API user queries the Status of a Menu Creation. If any of these errors are returned, the menu is not created.

Duplicate Property

  • Applies to categories, items, options, choices

  • pos_id must be unique within each collection

Example response

{
  "data": {
    "menuCreationRequest": {
      "status": "completed",
      "outcome": "failure",
      ...
      "errors": [
        {
          "message": "Each member of the 'items' collection must have a unique 'pos_id'",
          "details": {
            "count": 2,
            "pos_id": "item-1"
          }
        }
        ...

Recommended actions

  • Ensure each pos_id is unique within categories, items, options, choices

  • Use consistent ID naming scheme (e.g., CAT001, CAT002 for categories)

  • Validate uniqueness before submission

Reference Validation

  • Items referenced by categories must exist (item_pos_ids)

  • Options referenced by items must exist (option_pos_ids)

  • Choices referenced by options must exist (choice_pos_ids)

Example response

{
  "data": {
    "menuCreationRequest": {
      "status": "completed",
      "outcome": "failure",
      ...
      "errors": [
        {
          "message": "Referenced entity is not defined",
          "details": {
            "source": "categories",
            "source_name": "Catering Packages",
            "source_pos_id": "category-1",
            "reference_type": "items",
            "referenced_pos_id": "item-2"
          }
        }
        ...

Recommended actions

  • Verify all referenced pos_id values exist in their collections

Selection Size

Items cannot have multiple selections with the same size name.

Example response

{
  "data": {
    "menuCreationRequest": {
      "status": "completed",
      "outcome": "failure",
      ...
      "errors": [
        {
          "message": "Entity has duplicate selection sizes",
          "details": {
            "size": "1-5",
            "entity_name": "XL Deep Dish Pizza",
            "entity_pos_id": "item-1"
          }
        }
      ]...

Recommended actions

  • Use distinct size names for item selections

  • Consider using size codes instead of names if needed

Choice Selection Logic

For an Option Group:

  • The Maximum number of choices must be greater than or equal to the required minimum

  • A minimum choices requirement must be less than or equal to the total number of choices available

Example response

"menuCreationRequest": {
      "status": "completed",
      "outcome": "failure",
      "menuUuid": null,
      "errors": [
        {
          "message": "maxChoiceSelections must be greater than or equal to minChoiceSelections",
          "details": {
            "maxchoices": 1,
            "minchoices": 5,
            "entity_name": "Taco Bar",
            "entity_pos_id": "option-2"
          }
        },
        {
          "message": "minChoiceSelections must be less than or equal to count of Choices",
          "details": {
            "minchoices": 5,
            "entity_name": "Taco Bar",
            "entity_pos_id": "option-2",
            "choices_present": 3
          }
        }
      ],

Recommended actions

  • Ensure max_choice_selections >= min_choice_selections

  • Set min_choice_selections = 0 if selections are optional

  • Reduce min_choice_selections to match available choices

  • Add more choices to the option

  • Review option design for usability

Item-Choice Selection Mismatch

To ensure pricing structure is consistent between items and choices, a choice must have either 1 selection, or greater than or equal to the number of selections of the associated item.

Example response

{
  "data": {
    "menuCreationRequest": {
      "status": "completed",
      "outcome": "failure",
      "menuUuid": null,
      "errors": [
        {
          "message": "Choice must have either 1 selection, or >= selections than associated item",
          "details": {
            "item_pos_id": "item-1",
            "choice_pos_id": "choice-1",
            "option_pod_id": "option-1"
          }
        }
      ],

Recommended actions

  • Standardize selection structures across items and choices

  • Use single-selection choices when possible

Zero Priced Items

This error is returned when no menu items have a price.

Example response

{
  "data": {
    "menuCreationRequest": {
      "status": "completed",
      "outcome": "failure",
      "menuUuid": null,
      "errors": [
        {
          "message": "Too many zero priced items",
          "details": {
            "threshold": 100,
            "zero_price_percentage": 100
          }
        }
      ],

Recommended actions

  • Review pricing strategy

  • Ensure at least some items have prices > 0

  • Consider if zero-priced items are intentional

Meal Program Channel

If an item services the "Meal Program" channel:

  • It must be available to the customer in quantities of 1

  • All selection sizes within the item must serve 1

  • It cannot have a choice with sub quantities enabled

Example response

{
  "data": {
    "menuCreationRequest": {
      "status": "completed",
      "outcome": "failure",
      "menuUuid": null,
      "errors": [
        {
          "message": "Item must have quantityOptions of '>1'",
          "details": {
            "item_pos_id": "item-1",
            "quantity_options": ">5"
          }
        },
        {
          "message": "Selection must have serves = 1",
          "details": {
            "serves": 5,
            "item_pos_id": "item-1",
            "selection_pos_id": null
          }
        },
        {
          "message": "Item cannot have a choice with enableSubQuantities = true",
          "details": {
            "item_pos_id": "item-1",
            "choice_pos_id": "choice-1",
            "option_pos_id": "option-1"
          }
        }
      ],

Recommended actions

  • Set quantity_options: ">1" for Meal Program items

  • Review channel-specific requirements

  • Set serves: 1 for all selections on Meal Program items

  • Review serving size logic

  • Remove enable_sub_quantities from choices on Meal Program items

  • Review choice configuration for Meal Program compatibility

Utensils

  • An Option Group cannot mix utensil and non utensil choices

  • A Utensil Option Group cannot have required choices, utensils should always be optional

Example response

{
  "data": {
    "menuCreationRequest": {
      "status": "completed",
      "outcome": "failure",
      "menuUuid": null,
      "errors": [
        {
          "message": "Option 'Toppings Deep Dish Catering' mixes utensil and non-utensil choices.",
          "details": {
            "option_name": "Toppings Deep Dish Catering",
            "option_pos_id": "option-1"
          }
        },
        {
          "message": "Option 'Utensils' with utensil choices must not have min_choice_selections > 0.",
          "details": {
            "option_name": "Utensils",
            "option_pos_id": "utensils-1"
          }
        }
      ],

Recommended actions

  • Separate utensil choices into dedicated options

  • Review utensil choice categorization

  • Use choice_type_tags properly

  • Set min_choice_selections: 0 for utensil options

  • Make utensil selection customer-optional

Runtime Warnings

These are warnings that are aggregated during the course of Menu Creation. They do not prevent the menu from being created but are intended to highlight what we consider menu deficiencies. These are also returned as an array within the Status of a Menu Creation.

Image Extension

Acceptable Image Extensions:

  • gif

  • jpg

  • jpeg

  • png

Example response

{
  "data": {
    "menuCreationRequest": {
      "status": "completed",
      "outcome": "success_with_warnings",
      "menuUuid": "8eedb10c-8766-4241-9b66-cf471ad73534",
      "warnings": [
        {
          "message": "Invalid extension for file referenced by imageUrl.  Image will not be displayed.",
          "details": {
            "imageUrl": "test_image.xml",
            "entityType": "item",
            "entityPosId": "item-1"
          }
        },

Recommended actions

  • Convert images to supported formats

  • Update image URLs to point to supported formats

  • Verify image URLs are accessible

Mutually Exclusive Fields

Items with both lead_time and day_before_cutoff_time will default to lead_time.

Example response

{
  "data": {
    "menuCreationRequest": {
      "status": "completed",
      "outcome": "success_with_warnings",
      "menuUuid": "0c44976c-cef3-436c-96d3-91d470a8decf",
      "errors": [],
      "warnings": [
        {
          "message": "Item 'item-1' has both 'lead_time' and 'day_before_cutoff_time' defined, please provide only one.",
          "details": {}
        },

Recommended actions

  • Choose appropriate timing method for your business model

  • Remove one of the conflicting fields

  • Review timing logic consistency

Missing Utensils

ezCater encourages all Items have a utensils option associated with it.

Example response

{
  "data": {
    "menuCreationRequest": {
      "status": "completed",
      "outcome": "success_with_warnings",
      "menuUuid": "0c44976c-cef3-436c-96d3-91d470a8decf",
      "warnings": [
        {
          "message": "Item does not have a utensil choice mapped",
          "details": {
            "item_name": "Taco Bar",
            "item_pos_id": "item-2"
          }
        },

Recommended actions

  • Add utensil options to items

  • Create utensil choices with proper choice_type_tags

  • Review if utensils are required for specific items

Zero Priced Item

We do not support $0 Items on the Marketplace, they will be created but not shown to customers.

Example response

{
  "data": {
    "menuCreationRequest": {
      "status": "completed",
      "outcome": "success_with_warnings",
      "menuUuid": "0c44976c-cef3-436c-96d3-91d470a8decf",
      "errors": [],
      "warnings": [
        {
          "message": "Item with pos_id item-2-sel-1 has a price of $0.00.  It will not be displayed.",
          "details": {}
        }
Related Articles
Did this answer your question?