Skip to main content
Version: 0.6

Problem Reports


The IOTA DIDComm Specification is in the RFC phase and may undergo changes. Suggestions are welcome at GitHub #464.

  • Status: IN-PROGRESS
  • Last Updated: 2021-10-29

Problem reports are a standard DIDComm feature for reporting errors or warnings between parties. Using this mechanism is not a general requirement but it is a best practice for relaying informative errors and may improve human experience.


A problem report is a standard DIDComm message:

"type": "",
"id": "7c9de639-c51c-4d60-ab95-103fa613c805",
"pthid": "1e513ad4-48c9-444e-9e7e-5b8b45c5e325",
"body": {
"code": "e.p.xfer.cant-use-endpoint",
"comment": "Unable to use the {1} endpoint for {2}.",
"args": [
"escalate_to": "mailto:[email protected]"

Note that problem reports may still use sender authenticated encryption or even be signed DIDComm messages.

IOTA Problem Codes

We follow the notation for problem codes defined by the DIDComm specification. In general, we use the error sorter e and protocol scope p to indicate that problem reports result in the abandonment of a protocol.

In addition to the problem report descriptors in the DIDComm specification, we define the following non-exhaustive list of general problem report codes that may be sent during the course of any protocol:

e.p.msg.invalid-messageThe message is malformed or fails field constraints validation.
e.p.msg.unsupported-messageThe message type is unrecognised or unsupported by the recipient.
e.p.msg.invalid-stateThe recipient is unable to handle the type of message in its current state. Typically when an unexpected message is received in the middle of a protocol on the same thread. sender is required to authenticate to perform the requested action. sender is authenticated but lacks sufficient permissions to perform the requested action. recipient requires the message to use sender authenticated encryption. recipient requires the message to use anonymous encryption recipient requires a signed DIDComm message. general cryptography-related error. E.g. the signature in a message payload or on a signed DIDComm message fails validation, or sender authenticated encryption fails.
e.p.req.timeThe party has timed out waiting for a response.

These messages may be raised during or between protocols to inform the other party that something went wrong. A problem report with the error sorter e and protocol scope p terminates the protocol on the current thread and MAY be followed by a connection termination.

Unresolved Questions

  • Should we support the message scope m to allow resending / retrying individual messages?

Further Reading