Skip to main content

Letter lock error fields on updateLetter

Summary​

When updateLetter rejects a content change because the letter is locked (for example after it was marked Completed under strict letter mode), the LetterResponsePayload now includes optional structured fields alongside the existing error string.

Partners can use these fields to detect lock rejections without parsing free-text messages.

New LetterResponsePayload fields​

FieldTypeWhen present
reasonLetterResponseErrorReasonLock rejection (LETTER_LOCKED)
lockedAtDateTimeLock rejection
lockedReasonLetterLockReasonLock rejection (COMPLETED today)
suggestedActionLetterLockSuggestedActionLock rejection (CREATE_DUPLICATE)

Enum values are forward-compatible: clients should treat unknown enum values as opaque and continue to read error.

Compatibility​

  • The existing error string is unchanged and remains the human-readable message.
  • Successful updateLetter responses are unchanged; lock fields are omitted or null.
  • Public Letter reads do not expose lock metadata in this release.

Integration guidance​

  1. Refresh your GraphQL schema snapshot and regenerate clients.
  2. On updateLetter, when reason is LETTER_LOCKED, do not retry the same content update.
  3. Use suggestedAction: CREATE_DUPLICATE as the recommended recovery path: create a new letter with the desired content instead of mutating the locked record.
  4. Handle unknown future lockedReason or suggestedAction enum values defensively.

See also​