Guidelines for writing validator return messages

This guide is made to serve as a basic guide for people writing error / notice / info messages returned by validator.

The purpose is to help writing error messages in a way that they are:

  • informative
  • short
  • unambiguous 

Based on return message end-user has to make appropriate fixes so it is crucial that message information is transfered as efficiently as possible. It is worth noting that often the instruction used in implementation guide is not sufficient to be transfered into validator as it is. The instruction tells how to use the element, not what went wrong with the payment file.

For example EPC defines a usage rule for element AdrLine with text: "Only two occurrences are allowed." Using this text in validator when rule is triggered does not indicate explicitly why the message is shown or whether there is anything amiss in the payment file. In this case a better way of showing the information is  

"Occurrences of element 'AdrLine' exceed the maximum allowed number of 2."

Return message should tell the user what causes the message to be shown and an indication on how the possible issue can be fixed. 



Suggested message

Reason / comment

Required element missing

Mandatory element 'Dbtr/Nm' is missing.

Words "mandatory" and "missing" indicate how element is treated by the bank and why error is given. 

Recommended element missing Recommened element 'GrpHdr/CtrlSum' is missing.  

Invalid element given

Given element ‘RmtInf/Strd’ is not allowed.


Too many occurrences given Occurrences of element 'AdrLine' exceed the maximum allowed number of 2.  

Element value invalid

Invalid 'SvcLvl/Cd' value given. Only "SEPA" is allowed.

When the list of allowed values is short, it makes sense to present the valid values in the error message.

Element mandatory when parent element given (often referred as conditional)

Conditional element 'CdtrSchmeId/Id/PrvtId/Othr/Id' is missing. Data in the element is mandatory when 'PmtInf/CdtrSchmeId/' is given.

Element referred as conditional instead of mandatory. Reason for requiring the element is given

Element is too long Data in element 'Nm' exceeds the maximum length of 70 characters.  


XML element terminology is worth keeping in mind when writing the messages.