UID2-7505: Point v2 envelope error responses to encryption/decryption docs

[sunnywu]

Summary

Makes the v2 request-envelope parse errors in V2RequestUtil self-explanatory so callers who send an unencrypted body (e.g. a raw curl request with base64-encoded JSON) understand that the body must be an encrypted request envelope.

Private Operator customers repeatedly call /v2/token/generate directly with:

curl -X POST ".../v2/token/generate" \
  -H "Authorization: Bearer <key>" -H "X-UID2-Client-Secret: <secret>" \
  -d "$(echo -n '{"email_hash":"...","version":2}' | base64 -w 0)"

Because the body is base64 of plain JSON (not an encrypted v2 envelope), byte 0 fails the version check and the operator returns the opaque:

{"message":"Invalid body: Version mismatch.","status":"client_error"}

Nothing in that message tells the caller the real problem is that the payload must be encrypted. In a recent support thread this caused days of back-and-forth — the customer kept re-running curl-with-base64 tests, got "Version mismatch" each time, and mistook it for a server-side bug.

Change

Appends a hint to the three envelope-parse errors that fire when the body is not a valid encrypted envelope:

• Invalid body: Body too short. Check encryption method.
• Invalid body: Version mismatch.
• Invalid body: Check encryption key (ClientSecret)

The hint tells the caller the body must be an encrypted request envelope (base64-encoding JSON is not enough) and links to https://unifiedid.com/docs/getting-started/gs-encryption-decryption#encryption-and-decryption-code-examples.

The existing leading phrase of each message is preserved, so any downstream code that pattern-matches on the current text is unaffected.

Testing

• Updated testParseRequestWithTooShortBody to assert the leading phrase (via startsWith) plus the presence of the docs link.
• Added testParseRequestWithVersionMismatch, which feeds base64 of plain JSON (the exact curl failure mode) and asserts both the preserved Invalid body: Version mismatch. prefix and the docs link.
• mvn -Dtest=V2RequestUtilTest test → Tests run: 7, Failures: 0, Errors: 0.

Jira

UID2-7505

🤖 Generated with Claude Code