Feature request: Structured error response for INSUFFICIENT_FUND errors

[martynasselvenis-inventi]

Problem

When a transaction fails due to insufficient funds, the API returns an error with:

• errorCode: INSUFFICIENT_FUND
• errorMessage: "account(s) @CUSTOMER:xxx:CURRENT had/have insufficient funds"

The error message is unstructured text, requiring consumers to parse it with regex to extract the affected account(s).

Current behavior

{
  "errorCode": "INSUFFICIENT_FUND",
  "errorMessage": "account(s) @CUSTOMER:xxx:CURRENT had/have insufficient funds"
}

Proposed behavior

Include structured data in the error response with the affected account(s):

{
  "errorCode": "INSUFFICIENT_FUND",
  "errorMessage": "account(s) @CUSTOMER:xxx:CURRENT had/have insufficient funds",
  "details": {
    "accounts": ["@CUSTOMER:xxx:CURRENT"]
  }
}

Use case

When building payment systems, we need to programmatically identify which account(s) had insufficient funds to:

• Return meaningful error messages to API consumers
• Log specific account information for debugging
• Implement account-specific retry or fallback logic

Currently we rely on regex parsing which is fragile and may break if the message format changes.

Environment

• Formance SDK: Java
• Ledger API: v2