Errors

Transactions can include one or more errors. Each error has this general schema:

{
  "source": "counterparty",
  "code": "COUNTERPARTY_DETECTION_ERROR",
  "cause": {
    "message": "Counterparty detection error",
    "type": "Error"
  }
}

• source: the service that raised the error.
• code: a stable service-specific error code.
• cause: serialised error details (shape may vary depending on the type of error).

Dead-letter topics

Each Kafka interface has a corresponding dead-letter topic. A message is sent to a dead-letter topic in one of three scenarios:

1. The message could not be parsed, so the transaction information itself could not be read and forwarded for further processing.
2. An error was caught while enriching a transaction. The transaction still continues onward and is still sent to the egress topic, though some enrichment fields may be missing as a result.
3. An error occurred later in processing that meant the transaction could not be completed. In this case the transaction is not sent to the egress topic.

Message formats

For scenario 1 above, the message value can't be read, so the error can't be attached to the transaction itself. Instead the dead-letter message value is a JSON object with the following properties:

For scenarios 2 and 3, the error is added directly to the transaction before it's sent to the dead-letter topic. The exact message shape depends on the interface, but each transaction carries its error(s) as an array using the standard error format described above.

Example: ingress mapping error

If a transaction fails validation against the ingress schema - for example, a required field such as amount is missing or the wrong type - the message is sent to the dead-letter topic using the scenario 1 format:

{
  "error": {
    "source": "ingress-adapter",
    "code": "INGRESS_TRANSACTION_MAPPING_ERROR",
    "cause": {
      "message": "amount is required"
    }
  },
  "inputTopic": "transactions-ingress",
  "originalMessages": [
    {
      "headers": "{}",
      "key": "030a7556-e17d-432d-8afb-7a9f71128152",
      "value": "{\"transactionId\":\"123456\",\"accountId\":\"5382358854398\",\"accountType\":\"cash\",\"date\":\"2025-10-20T13:46:57.329Z\",\"description\":\"Tesco BriLL 293484 SS\",\"currency\":\"GBP\",\"status\":\"posted\"}"
    }
  ]
}

Messages in this format should not be resent unmodified, as they will fail again at the same point. The original message should be corrected (in this example, by adding a valid amount) before being sent through again.

Error scenario behaviour

The table below describes the expected behaviour for each error scenario.

There are other scenarios where the transaction may not be sent to egress, however the most common will be an ingress mapping error. If transactions are not being sent to egress and the schema has been verified, please contact Moneyhub support.

Resolving issues and replaying transactions

Most transactions on a dead-letter topic will also have been sent to egress (see scenario 2 above), just without all enrichment fields populated. Transactions can be replayed back through the pipeline once any underlying issue has been fixed, in order to pick up full enrichment. Some examples:

• Data issue that can be fixed: a transaction couldn't be enriched because the description was in an unexpected encoding. The encoding should be corrected before replaying the transaction.
• Data issue that may not be fixable: a transaction couldn't be enriched because it was missing a description. In this case you may decide to leave the transaction as-is rather than replaying it.
• Transient issue: a transaction couldn't be processed because of a brief, temporary issue with a dependency. In this case the transaction can simply be replayed unmodified once the underlying issue has cleared, which is usually a matter of seconds or minutes.

Error codes

Below are the possible error codes that may appear on transactions. Please note some errors mean that the transaction won't get sent to egress. Please see above for those scenarios.