Loading

Salesforce Loyalty Management: "An unexpected error occurred" APIFault When Creating a Loyalty Program Member via API

Julkaisupäivä: Jun 23, 2026
Kuvaus

This issue occurs when an external integration, such as MuleSoft, calls the Salesforce Loyalty Management member-enrollment API and receives an unexpected-error APIFault instead of a successful enrollment response.

Typical fault examples include:

  • exceptionCode=UNKNOWN_EXCEPTION exceptionMessage=An unexpected error occurred
  • Fault messages containing references to:
    • Watchlist evaluation
    • AMP (Audience Membership Pipeline)
    • List-search processing
    • Realtime Loyalty processing

Customers commonly report:

  • "We are unable to create new loyalty member via Salesforce API."
  • "We are facing failure in the loyalty member creation API."
  • "Member enrollment through MuleSoft is blocked."
  • "The same enrollment request fails every time."

The issue can occur when:

  • The integration user does not have access to all Loyalty objects required during enrollment.
  • The enrollment process cannot resolve related promotions, membership rules, or watchlist evaluations.
  • The Loyalty realtime service encounters a cache timeout while retrieving promotions associated with the Loyalty Program.
  • The enrollment request contains missing, invalid, or duplicate membership data.

Because the failure often occurs during downstream enrollment processing rather than request validation, the API may return a generic UNKNOWN_EXCEPTION fault instead of a field-specific error.

Ratkaisu

Work through the following causes in order. Because the APIFault is generic, verify each condition before proceeding to the next one.

Cause 1: The integration user lacks required Loyalty Management access

  1. Navigate to Setup > Users > Permission Sets.
  2. Open the permission set assigned to the integration user.
  3. Under Object Settings, verify the user has the required permissions on Loyalty objects used during enrollment.
  4. Confirm the user can access:
    • Loyalty Program Member
    • Loyalty Member Currency
    • Loyalty Program
    • Loyalty Program Currency
    • Any additional Loyalty objects referenced by enrollment automation
  5. Verify API Enabled is granted.
  6. Verify the user has the required Loyalty Management permissions assigned through the appropriate Loyalty permission set.
  7. Review Field-Level Security and confirm the integration user can create or update all fields included in the enrollment request.

Retry the enrollment request.

Cause 2: Related promotions, membership rules, or watchlist evaluation cannot be resolved

If the fault references watchlist processing, AMP evaluation, or Loyalty realtime processing:

  1. Identify the Loyalty Program referenced by the enrollment request.
  2. Open the Loyalty Program and confirm the program is active.
  3. Review the program's active promotions and enrollment-related configuration.
  4. Verify that:
    • Promotions are active and valid.
    • Effective dates are current.
    • Membership rules are configured correctly.
    • Watchlist-related configuration is available and valid.
  5. Correct any inactive, invalid, or inconsistent program configuration.

Retry the enrollment request.

Cause 3: Realtime Loyalty cache timeout while retrieving program promotions

In some cases, the failure occurs while the Loyalty realtime service retrieves related promotion data for the program.

  1. Review the fault details for references to a realtime Loyalty endpoint similar to:

    /services/data/vXX.0/connect/realtime/loyalty/programs/<ProgramName>

  2. Retry the request after a short delay.
  3. Reduce concurrent enrollment traffic from the integration if large batches are being submitted.
  4. Configure retry logic with exponential backoff in the integration platform.
  5. Re-test the enrollment request using the same payload.

Transient cache or retrieval failures may succeed on a subsequent retry.

Cause 4: Missing required values or duplicate membership information

  1. Review the enrollment request payload.
  2. Verify all required enrollment fields are populated.
  3. Confirm that:
    • The Loyalty Program exists.
    • The membership number is unique.
    • Any referenced Contact, Individual, or Account record exists.
    • The integration user has access to referenced records.
  4. Check for duplicate member records that could prevent enrollment.
  5. Correct any invalid or duplicate values.

Retry the enrollment request.

Verification

  1. Replay the original enrollment request using a new, unique membership number.
  2. Confirm the API returns a successful response.
  3. Verify that a new Loyalty Program Member record is created.
  4. Confirm that enrollment-related records and balances are generated successfully.
  5. Verify that the response no longer contains:
    • exceptionCode=UNKNOWN_EXCEPTION
    • exceptionMessage=An unexpected error occurred
Knowledge-artikkelin numero

005387403

 
Ladataan
Salesforce Help | Article