[$250] [HR Import] Handle 429 Merge daily sync limit error with popup

[melvin-bot]

Description

We need to handle the HTTP 429 error response from the Merge API when the daily sync limit is reached, and display an appropriate popup to the user.

Error Details

When the daily sync limit is exceeded, the auth-via-api endpoint returns:

{
    "jsonCode": 429,
    "message": "429 Merge daily sync limit reached, try again tomorrow",
    "source": "auth-via-api",
    "onyxData": [],
    "requestID": "9ffbe2dfba19ae4b-LAX"
}

Design

The popup design is available in Figma:
https://www.figma.com/design/cSAzrV7arFMJ62Ao1St8Qh/Merge.dev-Integration?node-id=16-5946&t=LaBrBcneCC0kpL8I-0

Requirements

• Detect the 429 response from auth-via-api
• Display popup matching the Figma design
• Inform user to try again tomorrow
• Gracefully handle the rate limit state

Upwork Automation - Do Not Edit

• Upwork Job URL: https://www.upwork.com/jobs/~022057805761450217854
• Upwork Job ID: 2057805761450217854
• Last Price Increase: 2026-05-22

[melvin-bot]

Auto-assigning issues to engineers is no longer supported. If you think this issue should receive engineering attention, please raise it in #whatsnext.

[MelvinBot]

Proposal

What is the root cause of that problem?

When syncMergeHR() is called (MergeHR.ts:25-47), it sends WRITE_COMMANDS.SYNC_POLICY_TO_MERGE with failureData that only clears the sync progress spinner — it does not set any error state or trigger any popup. When the server returns jsonCode: 429, applyHTTPSOnyxUpdates (OnyxUpdates.ts:45-66) applies the client failureData (clearing the spinner) and the sync silently fails with no user-facing feedback about the rate limit.

There is no jsonCode 429 constant defined in CONST/index.ts and no client-side handling for this specific error anywhere in the codebase.

What changes do you think we should make in order to solve the problem?

The server already returns the 429 error with onyxData that should set connections.merge_hris.lastSync fields (isSuccessful: false, errorDate, errorMessage). The client needs two things:

1. Inline error (should work automatically): If the server's onyxData correctly sets lastSync.errorMessage, the existing HRProviderCard.tsx:54-57 error display will show the error inline — no client code change needed for this part.

2. Popup modal (new code needed): Extend useHRSyncResultsModal (or create a companion hook) to also watch for sync failure transitions — when connectionSyncProgress transitions from an active sync stage to null (cleared by failureData) and lastSync.isSuccessful === false with an errorMessage containing the 429 rate limit text, show a popup modal matching the Figma design. This follows the same reactive pattern the codebase already uses for successful sync results.

The modal should use the useConfirmModal hook (already imported in HRProviderCard) or the global useModal pattern, displaying the rate limit message and a single dismiss button.

Investigation details

Data flow for the 429 error:

1. User taps "Sync Now" → syncConnection() routes to syncMergeHR(policyID) (connections/index.ts:154-163)
2. syncMergeHR sends write command with optimisticData (sets sync spinner) and failureData (clears spinner)
3. Server calls Merge API, gets 429 rate limit, returns HTTP 200 with jsonCode: 429 and onyxData
4. applyHTTPSOnyxUpdates applies server onyxData first (sets lastSync error fields), then client failureData (clears sync progress)
5. Gap: No popup is triggered — useHRSyncResultsModal only watches for JOB_DONE with a result payload, not for failures

Key distinction: This is jsonCode 429 (inside an HTTP 200 response), not HTTP 429. HTTP 429 is caught separately in HttpUtils.ts:122-128 as a network-level throttle. The Merge rate limit error flows through normal response processing.

Existing error patterns used as reference:

• Inline: getSynchronizationErrorMessage() in utils.tsx:349-383 reads lastSync.errorMessage
• Imperative error setting: setConnectionError() in connections/index.ts:321-334
• Modal on sync completion: useHRSyncResultsModal hook

Open question: Confirm that the server already includes proper onyxData setting lastSync fields when returning jsonCode 429 for SyncPolicyToMerge. If not, a server-side change is also required.

---

Next Steps for Contributor+ team: Reply with @MelvinBot implement this to create a draft PR, @MelvinBot <your feedback> to refine this analysis, or explain why you are rejecting Melvin's proposal.

[melvin-bot]

Triggered auto assignment to Contributor-plus team member for initial proposal review - @gijoe0295 (External)