fix(java): read nested and inferred error messages in typed errors

Merged
2Y
7d ago
+617-23

Why

Java typed error exceptions built their message only from a top-level field marked x-speakeasy-error-message: true. Otherwise getMessage() was the literal "API error occurred". A common error envelope keeps the message one level down:

{"error": {"message": "Something went wrong.", "code": "invalid_request"}}

TypeScript, Python and C# already resolve this through the shared getOrInferErrorMessageFieldDeep helper (templates/templates/common/common/utils.ts). It finds a marked field at any depth, or else infers a top-level message string, or else error.message. Java ignored a nested marker and did no inference.

What changed

  • errorMessageExpression (templates/templates/javav2/includes/templating.ts) now uses getOrInferErrorMessageFieldDeep when there is no top-level marker. A multi-field path generates a null-safe chain:
    Utils.valueOrElse(
        Optional.ofNullable(data)
            .map(v0 -> Utils.valueOrNull(v0.error()))
            .map(v1 -> Utils.valueOrNull(v1.message()))
            .orElse(null),
        "API error occurred")
    
    Utils.valueOrNull is overloaded for T, Optional<T> and JsonNullable<T>, so each step unwraps whatever the getter returns under every getterStyle (presence-aware, raw, always-optional).
  • If the field holding the message isn't a string, it is converted to one: enums through value(), everything else through toString(). Previously, a marked non-string field at the top level failed to compile.
  • A top-level marked string field still takes precedence and keeps its existing generated output byte-for-byte.
  • Unskipped errors-optional-nullable-error-message and errors-optional-nullable-error-message-nested, and added Java tests for both. The nested test covers a cause that is both present and absent.

Behaviour change

A typed error whose schema has a top-level message string or an error.message string, and no marker, now returns that message from getMessage() instead of "API error occurred". This matches TypeScript, Python and C#. The review SDK shows this for BadRequestResponseException and RequestTimeoutError. EventStreamAdditionalTest now expects the inferred message.

Testing

  • TARGET=primary make test-javav2: 732 passed, 15 skipped.
  • TARGET=review make build-javav2 regenerated zSDKs/sdk-javav2.
  • make lint and make check-template-javav2 pass.
  • Generated throwaway SDKs from a focused spec and compiled them under getterStyle presence-aware, raw and always-optional, plus languageVersion: 8 and nullFriendlyParameters: true. Checked runtime messages for these cases:
    • inferred error.message and top-level message
    • a marker nested under an optional+nullable object (present, null, absent)
    • a required chain with a nullable final field
    • a marked field of each non-string type: integer, string enum, integer enum, untyped, date-time
    • reserved-word field names, allOf, and a recursive schema
  • Markers inside arrays, maps and oneOf members aren't followed (same as TypeScript), so those fall back to the default message.

Public-safety check

  • This change contains no credentials, customer documents, private repository URLs, private filesystem paths, or unredacted private logs.
  • Title, body, comments, and commit messages name no customers or customer-derived identifiers, private paths or trackers, or workflow provenance, and are understandable without private context (.claude/skills/public-repo-communication/SKILL.md).
  • Generated fixtures and review SDK changes are public-safe.
  • I reviewed git diff --check.

Summary by cubic

Fixes Java typed error exceptions so getMessage() reads nested or inferred error messages instead of always returning "API error occurred", matching TypeScript, Python, and C#.

Bug Fixes

  • Honors a field marked x-speakeasy-error-message: true at any depth; without a marker, falls back to a top-level message string, then error.message.
  • Uses null-safe Optional chains so null data, explicit JSON null, or missing optional+nullable fields fall back to the default message instead of throwing.
  • Converts non-string message fields to strings via value() for enums, except discriminator enums whose getters already return String.
  • Keeps a top-level marked string field taking precedence with byte-for-byte identical output.
  • Unskips errors-optional-nullable-error-message and errors-optional-nullable-error-message-nested; BadRequestResponseException, RequestTimeoutError, and EventStreamAdditionalTest now expect the inferred message.