[Discussion] i18n-incompatible error patterns

[KaveeshaPiumini]

Background

Thunder's service layer uses a structured ServiceError type where both the error title and description are core.I18nMessage values — a static Key for translation lookup and a DefaultValue English fallback. The intent is that the translation system resolves the key at response time; the DefaultValue is only a last resort.

type I18nMessage struct {
    Key          string `json:"key"`
    DefaultValue string `json:"defaultValue"`
}

This design works well when error messages are fully static. It breaks down in two related scenarios that are widespread in the current codebase.

Problems

1. Runtime values baked into DefaultValue

At many call sites, a runtime value is embedded directly into DefaultValue via string concatenation or fmt.Sprintf:

// application/service.go — 6 sites like this
return serviceerror.CustomServiceError(ErrorCertificateClientError, core.I18nMessage{
    Key:          "error.applicationservice.delete_certificate_failed_description",
    DefaultValue: "Failed to delete application certificate: " + certErr.ErrorDescription.DefaultValue,
})

// design/layout/mgt/service.go
DefaultValue: fmt.Sprintf("Layout is being used by %d application(s)", count)

// idp/utils.go
DefaultValue: fmt.Sprintf("property '%s' is not supported for IDP type '%s'", propName, idpType)

The Key is static, but the full message is constructed at Go runtime. A translation file maps keys to templates — but there is no mechanism to pass count, propName, or idpType into that template after the fact. The DefaultValue a translator receives is an already-interpolated English string. They cannot produce a parameterized translation for it.

This affects ~20 call sites across application, authn/oauth, authn/otp, authn/google, flow/flowexec, design/layout, design/theme, idp, userschema, and system/i18n/mgt.

2. Cross-service error message embedding

When Service A wraps a client error from Service B, it reads B's DefaultValue as a plain Go string and concatenates it into A's DefaultValue:

// authn/otp/service.go
DefaultValue: fmt.Sprintf("Error verifying OTP: %s", svcErr.ErrorDescription.DefaultValue)

// userschema/service.go
DefaultValue: fmt.Sprintf("%s : code - %s", ErrorConsentSyncFailed.ErrorDescription.DefaultValue, err.Code)

// flow/flowexec/service.go
DefaultValue: fmt.Sprintf("Error while retrieving application: %s", err.ErrorDescription.DefaultValue)

Here the problem compounds: B's DefaultValue is the English fallback, not a resolved translation. A reads that English string and welds it into its own message. Even if B's key could have been translated, the translation is discarded at the point A reads .DefaultValue. A's key now points to a message that contains untranslatable English from B, forever.

3. Inconsistent cross-service error propagation

There is no documented policy for whether Service A should re-wrap or pass through Service B's errors. Both patterns coexist today:

• Pass-through (27+ instances across application, consent, user, authn, flow, userschema, ou, group, notification, resource, jose/jwt): return svcErr — B's error code and namespace reach A's caller intact.
• Re-wrap (~13 instances, primarily in application and authn services): A creates a new error with A's code, embedding B's DefaultValue — which is where Problems 1 and 2 currently originate.

Proposed solution

Parameterized I18nMessage

Extend I18nMessage with a Params field, and let the translation layer perform {placeholder} substitution at resolution time:

// Before
core.I18nMessage{
    Key:          "error.layoutservice.layout_in_use_description",
    DefaultValue: fmt.Sprintf("Layout is being used by %d application(s)", count),
}

// After
core.I18nMessage{
    Key:          "error.layoutservice.layout_in_use_description",
    DefaultValue: "Layout is being used by {count} application(s)",
    Params:       map[string]string{"count": strconv.Itoa(count)},
}

Translation file entry:

error.layoutservice.layout_in_use_description = Das Layout wird von {count} Anwendung(en) verwendet

The translation layer substitutes {count} at response time. The DefaultValue also uses the placeholder as fallback, keeping the contract consistent.

For cross-service errors where A wraps B's message: A passes B's Key and Params as a nested context, rather than reading DefaultValue. The exact representation (a second I18nMessage field on ServiceError, a WrappedError field, or just forwarding B's key as a param value) is a design decision for the team.

Cross-service Error Propagation Policy

The codebase should be standardized around a single, agreed-upon approach from the options below.

Approach 1 — Re-wrap always

Service A always returns an A-typed error regardless of where the failure originated.

• Error codes stay predictable at each layer's API boundary — callers only ever see errors from the service they called.
• Requires parameterized i18n first. Without it, re-wrapping means reading B's DefaultValue as a plain string and embedding it into A's message, which is exactly the bug being fixed. Re-wrap without parameterization is strictly worse than pass-through.

Approach 2 — Pass-through always

Service A returns B's error as-is when the failure originates from B.

• B's translatable Key (and eventually Params) reach the caller without modification — translation works correctly.
• Trade-off: B's error code namespace leaks into A's API surface. Callers may receive error codes like CERT-1001 from the application service endpoint, which feels like an abstraction leak.

Hybrid (suggested in the discussion)

• Leaf/infra services (cert, OTP, notification, JWT) are implementation details — their errors are re-wrapped by the orchestration service calling them.
• Peer orchestration services (application, flow, authn calling each other) pass errors through as-is.

Open questions

1. Do we adopt parameterized I18nMessage? If yes, what is the substitution contract — {name} placeholders, a dedicated struct, something else? Does the DefaultValue also use placeholders, or remain a pre-interpolated fallback?

2. For cross-service errors where A wraps B's client error: should A carry B's I18nMessage (key + params) as structured context, or is it acceptable to only surface A's own key with no reference to B's message?

3. Re-wrap vs pass-through as the default policy: which do we prefer, and should there be a documented rule distinguishing orchestration services from leaf/infra services?

[ThaminduDilshan]

Another alternative is to allow embedding a service error within a service error. So the API error responses will have a stack of errors.

Ex:

{
    "code": "APP-1004",
	"message": {
		"key": "error_appsvc_i18n_resolution",
		"defaultValue": "Error resolving i18n for application"
	},
	"description": {
		"key": "error_appsvc_i18n_resolution_desc",
		"defaultValue": "An error occurred while resolving i18n keys for the application service."
	},
	"embeddedError": {
		"code": "I18N-1001",
		"message": {
			"key": "error_i18nsvc_resolution",
			"defaultValue": "Invalid i18n key"
		},
		"description": {
			"key": "error_i18nsvc_resolution_desc",
			"defaultValue": "The provided i18n key {{key}} does not conform to the expected format."
		}
	}
}

This can go into multiple levels.

Ex:

{
    "code": "APP-1004",
	"message": {
		"key": "error_appsvc_i18n_resolution",
		"defaultValue": "Error storing i18n for application"
	},
	"description": {
		"key": "error_appsvc_i18n_resolution_desc",
		"defaultValue": "An error occurred while storing i18n keys for the application."
	},
	"embeddedError": {
		"code": "I18N-1001",
		"message": {
			"key": "error_i18nsvc_resolution",
			"defaultValue": "Error storing i18n values"
		},
		"description": {
			"key": "error_i18nsvc_resolution_desc",
			"defaultValue": "An error occurred while storing i18n values for the application."
		},
		"embeddedError": {
			"code": "DB-1001",
			"message": {
				"key": "error_db_unexpected",
				"defaultValue": "Unexpected value"
			},
			"description": {
				"key": "error_db_unexpected_desc",
				"defaultValue": "An unexpected value was encountered in the database query."
			}
		}
	}
}

However this may not be interpretable in UI layers in a UX friendly manner. Hence I also prefer your suggestion. But we need to evaluate and see whether it can cater all such requirement.

---

For cross-service errors where A wraps B's message: A passes B's Key and Params as a nested context, rather than reading DefaultValue. The exact representation (a second I18nMessage field on ServiceError, a WrappedError field, or just forwarding B's key as a param value) is a design decision for the team.

Can you come up with a example for this? What will be the templated error and error description for service A error? I guess it will have a templated identifier for a possible error returned from service B (Note that at service A we don't know which error being returned from service B). It's not just about passing parameters from underline service. We need to return it's error and/ or error description as well to narrow down the root cause.

Also consider a scenario where service A invokes service B which invokes service C (A -> B -> C). Service C returns an error with the actual root cause for the failure.

---

Also we have defined a pattern for templated placeholders. Let's follow the same pattern here if we're proceeding with that implementation

[KaveeshaPiumini]

1. I’m also aligned with a similar approach here. The naming embeddedError works, though cause might be slightly more semantically precise as it conveys directionality (i.e., B caused A’s failure). That said, either naming is fine as long as we standardize on one and use it consistently across the codebase.

On the UX concern: I initially shared the same hesitation, but on further evaluation, the structured error chain actually provides more flexibility to the UI compared to a flat, pre-interpolated string. With a structured approach, the UI can decide how to render the error — for example, as a collapsible “Details” section, a breadcrumb, or even a stack trace-style view. In contrast, a flat string forces a single representation, effectively baking UI decisions into the backend. This approach allows different clients (e.g., CLI vs UI) to present the error in a way that best fits their context.

---

2. The key idea here is that Service A’s description does not need to include placeholders for errors coming from Service B. Each service defines a static, self-contained description of what it was attempting to do. Any downstream error is propagated as structured data via the embeddedError field, without any string interpolation at intermediate layers.

For example, in an A → B → C flow:

• Service C (leaf) returns the root cause with its own parameters.
• Service B wraps C’s error without needing to know its structure or message.
• Service A wraps B’s error in the same way.

A → B → C example:

Service C (leaf — Certificate service, actual root cause):

return serviceerror.CustomServiceError(ErrorCertificateNotFound, core.I18nMessage{
    Key:          "error.certservice.cert_not_found_description",
    DefaultValue: "Certificate {{certId}} does not exist",
    Params:       map[string]string{"certId": certID},
})

Service B (Application service — doesn't know which cert error C returned):

// certErr is whatever C returned; B just knows something in the cert service failed.
// B's DefaultValue is static — no embedded C string.
return serviceerror.WrapServiceError(
    ErrorCertificateClientError,
    core.I18nMessage{
        Key:          "error.applicationservice.delete_certificate_failed_description",
        DefaultValue: "Failed to delete application certificate",
    },
    certErr, // → becomes embeddedError
)

Service A (FlowExec — doesn't know which app-level error B returned):

// err is whatever B returned (which already has embeddedError = C's error).
// A's DefaultValue is static — no embedded B string.
return serviceerror.WrapServiceError(
    ErrorApplicationRetrievalClientError,
    core.I18nMessage{
        Key:          "error.flowexecservice.error_retrieving_application_description",
        DefaultValue: "Error while retrieving application",
    },
    err, // → becomes embeddedError (which itself has embeddedError = C's error)
)

Wire response:

{
  "code": "FE-4001",
  "description": {
    "key": "error.flowexecservice.error_retrieving_application_description",
    "defaultValue": "Error while retrieving application"
  },
  "cause": {
    "code": "APP-5001",
    "description": {
      "key": "error.applicationservice.delete_certificate_failed_description",
      "defaultValue": "Failed to delete application certificate"
    },
    "cause": {
      "code": "CERT-4041",
      "description": {
        "key": "error.certservice.cert_not_found_description",
        "defaultValue": "Certificate {certId} does not exist",
        "params": { "certId": "abc-123" }
      }
    }
  }
}

On the client side, each layer can be resolved independently using the i18n keys. Parameters (e.g., {{certId}}) are substituted only after resolving the corresponding translation template. This allows the UI to compose and render the error chain as needed, without any backend coupling to presentation logic.

---

3. Just to confirm — are you suggesting that we standardize on using {{placeholder}} (double curly braces) to align with the existing pattern?

[ThaminduDilshan]

1. I also don't have a naming preference. Let's pick the best option

2. Yes. But it's not just curly braces. We have defined a pattern to be used in flow definitions to refer different parameters. We should follow a unified pattern

[KaveeshaPiumini]

Alternative Approaches

Alternative 1: Flat errors array

Instead of a nested chain, each service appends to a flat list of errors ordered from outermost to root cause:

{
  "code": "FE-4001",
  "description": {
    "key": "error.flowexecservice.error_retrieving_application_description",
    "defaultValue": "Error while retrieving application"
  },
  "errors": [
    {
      "code": "APP-5001",
      "description": {
        "key": "error.applicationservice.delete_certificate_failed_description",
        "defaultValue": "Failed to delete application certificate"
      }
    },
    {
      "code": "CERT-4041",
      "description": {
        "key": "error.certservice.cert_not_found_description",
        "defaultValue": "Certificate {{certId}} does not exist",
        "params": { "certId": "abc-123" }
      }
    }
  ]
}

Pro: Simpler for the client — no recursive traversal, just iterate an array.
Con: Loses causal direction. A flat list shows which services were involved but not which error caused which. For A → B → C, [APP, CERT] is ambiguous.

---

Alternative 2: Pass-through (no wrapping at peer boundaries)

Service A simply returns B’s error as-is when the failure originated from B:

app, err := s.appService.GetApplication(...)
if err != nil {
    return err // B's error passes through unchanged
}

B’s Key, Params, and error code reach the client intact — no translation context is lost.

Pro: Zero structural changes. Existing I18nMessage with Params is sufficient. No changes needed to ServiceError or ErrorResponse.
Con: B’s error codes (e.g., CERT-4041) leak into A’s API surface, breaking abstraction. Also loses A’s context entirely.

---

Alternative 3: Cause details in structured logs only

Keep ServiceError flat at the API boundary. Service A logs the full cause chain with a correlation ID and returns a clean top-level error:

logger.Error("Certificate operation failed",
    log.String("correlationId", reqID),
    log.String("cause_code", certErr.Code),
    log.String("cause_key", certErr.ErrorDescription.Key),
)

return serviceerror.CustomServiceError(ErrorApplicationClientError, core.I18nMessage{
    Key:          "error.applicationservice.delete_certificate_failed_description",
    DefaultValue: "Failed to delete application certificate",
})

Pro: No structural changes. API surface remains clean.
Con: Root cause is only available via logs. API consumers cannot diagnose issues without log access.

---

Alternative 4: RFC 9457 Problem Details

Adopt the standard HTTP API error format with support for nested causes:

{
  "type": "https://thunder.example.com/errors/flow/retrieval-failed",
  "title": "Error retrieving application",
  "detail": "Error while retrieving application",
  "i18n": {
    "key": "error.flowexecservice.error_retrieving_application_description",
    "params": {}
  },
  "cause": {
    "type": "https://thunder.example.com/errors/app/cert-client-error",
    "detail": "Failed to delete application certificate",
    "i18n": {
      "key": "error.applicationservice.delete_certificate_failed_description"
    },
    "cause": {
      "type": "https://thunder.example.com/errors/cert/not-found",
      "detail": "Certificate abc-123 does not exist",
      "i18n": {
        "key": "error.certservice.cert_not_found_description",
        "params": { "certId": "abc-123" }
      }
    }
  }
}

Pro: Standardized and widely recognized. Supports nested causes.
Con: Requires significant structural changes (e.g., code → type, description → detail).

---

Summary

Approach	i18n-safe	Root cause visible	API namespace clean	Structural change
embeddedError chain	Yes	Yes (full chain)	Yes	Moderate
Flat errors array	Yes	Partial (no causality)	Yes	Moderate
Pass-through	Yes	Yes (direct)	No	Minimal
Logs only	Yes	No (logs required)	Yes	None
RFC 9457	Yes	Yes (full chain)	Yes	Large

The embeddedError chain and the flat errors array are the two most practical options. The key decision is whether the client needs to understand causality (which error caused which) or simply participation (which errors occurred).

[ThaminduDilshan]

Alternative 1 doesn't give the order as you suggested.

---

Alternative 2 will not be scalable with our plan to document all API error codes in respective swagger definitions. If service A invokes service B, and service B invokes service C, we have to document all three services' errors in service A related swagger definition.

We can say instead of per API error codes, we're going to define error codes in a generic way. But errors returned from a particular API will be uncontrolled. It can return any error defined in server

Also IMO by invoking service A, I should get a type A error, not something else

---

Alternative 3 hard to analyze client errors. Client applications will not be able to handle errors on their own. This is not going to work

---

Alternative 4 has the same approach proposed in #2392 (comment). It's just that we use different keys.