Skip to main content

Clarity and Consistency in Error Messages

Clear and consistent error messages are essential for helping users understand and resolve data validation issues. Unlike rule definitions, which are technical, error messages should be user-friendly and actionable.

Guiding Principles​

Be Clear and Concise​

Avoid technical jargon. Explain the error in simple terms that a business user can understand.

  • ❌ Bad: "Rule violation: 'isTradeItemAConsumerUnit' is true but 'consumerFirstAvailabilityDateTime' is null."
  • ✅ Good: "The 'Consumer First Availability Date' must be provided for a consumer unit."

Provide Actionable Guidance​

Tell the user exactly what they need to do to fix the problem.

  • ❌ Bad: "Invalid data."
  • ✅ Good: "The net weight is required for all food products."

Be Specific​

Reference the specific fields or values that are incorrect.

  • ❌ Bad: "A date is incorrect."
  • ✅ Good: "The 'End Availability Date' cannot be before the 'Start Availability Date'."

Maintain a Consistent Tone​

Use a helpful and professional tone. Avoid blaming the user.

  • ❌ Bad: "You made an error."
  • ✅ Good: "There is a conflict between the 'Packaging Type' and the 'Platform Type'."

Formatting Error Messages​

Highlight Key Terms​

Use single quotes to highlight attribute names or specific values to draw attention to them.

Example:

✅ The attribute 'Percentage Of Alcohol By Volume' must be filled in because of the chosen GPC Brick Code.

When dealing with rules that span multiple levels of a product hierarchy, make the context clear in the error message.

On Every Level​

✅ 'Is Packaging Marked Returnable' must be filled in on every level of the packaging hierarchy.

Referencing Other Levels​

✅ The item is not a base unit, so you must provide the 'Quantity Of Children', 'Total Quantity Of Next Lower Level Trade Item', 'Child Trade Item GTIN', and 'Quantity Of Next Lower Level Trade Item'.

By following these guidelines, you can create error messages that empower users to correct their data efficiently and accurately.