Help Desk Data Migration Failed? The Engineer's Rescue Guide

If your help desk migration just failed — data is missing, tickets are corrupted, or your script stalled halfway through — stop everything. Do not re-run the failed job. Do not let agents work in the half-migrated target system. Every new ticket, every agent reply, every status change in either system right now is widening the gap between what you have and what you need.

This guide is a structured recovery plan for engineers dealing with a broken help desk migration. It covers emergency triage, root cause diagnosis, sandbox validation, delta migration for in-flight data, reconciliation checks, and a clear decision framework for when to roll back versus push forward. If you have already read our common help desk migration mistakes guide and still ended up here, you are not alone — most failed migrations share the same handful of root causes.

Emergency Triage Checklist: Stop the Bleeding

Do these five things right now, in order. Time matters.

1. Stop writes to the target system. Disable all inbound email routing, chat widgets, and API integrations pointing at your new helpdesk. If agents are already working in the new system, pause them. Every ticket created in the target during a partial migration makes reconciliation exponentially harder. If Intercom is the target, disable email notifications before importing historical tickets so you do not spam customers during recovery. (developers.intercom.com)

2. Re-route all traffic to the source system. Ensure all incoming emails, webhooks, and integrations are pointing to your old helpdesk. Your support team must continue working in the legacy environment until the data integrity issue is resolved. Until proven otherwise, the old helpdesk stays authoritative.

3. Export full backups from both systems. Pull a complete export from your source helpdesk using its API or built-in export. Then capture the target system's current state — ticket count, user count, last ticket ID, attachment status. Store backups outside both platforms: an S3 bucket, Google Cloud Storage, or a local drive.

4. Preserve migration logs and error details. Save request bodies, HTTP response codes, Retry-After headers, and any rate-limit metadata from the failed run. You need to know if you hit a 429 Too Many Requests, a 413 Payload Too Large, or a 422 Unprocessable Entity. These logs are the forensic trail that determines your recovery path. Intercom, Freshdesk, and Zendesk all expose rate-limit behavior in response headers that materially changes rescue design. (developers.intercom.com)

5. Disable automations and triggers on both sides. Automations in the target system — welcome emails, SLA timers, assignment rules — will fire on partially-imported data, creating noise that masks real problems. Zendesk notes that imported tickets do not run triggers and do not bring in ticket metrics like first reply time, so production behavior and imported history will not match unless you account for it. (support.zendesk.com)

HTTP Error Code Reference

Before you can diagnose the root cause, you need to understand what your logs are telling you. Here is what the three most common error codes mean in a migration context and what to do about each:

A 422 is almost always a mapping problem, not a rate limit or infrastructure problem. If your logs show a high volume of 422 responses, the root cause is structural — a field that exists in the source has no valid equivalent in the target. No amount of retrying will fix it without changing the transformation logic.

Why DIY and Automated Help Desk Data Migrations Fail

Most failed help desk migrations share one of five root causes. Understanding yours determines the recovery path.

API Rate Limits That Kill Extraction Scripts

The most common silent failure. Your script starts strong, then slows to a crawl or starts throwing 429 Too Many Requests errors.

Zendesk caps incremental export endpoints at 10 requests per minute on standard plans. With the High Volume API add-on, that increases to 30 requests per minute. DIY scripts that do not implement proper cursor-based pagination and exponential backoff will stall or silently drop pages of results. (developer.zendesk.com)

Intercom distributes its per-app limit of 10,000 requests per minute into 10-second windows — roughly 1,666 operations per 10-second period. If your script uses heavy concurrency and fires 2,000 requests in a 3-second burst, Intercom will immediately return 429 errors, even if total per-minute usage is well under the cap. This windowed rate limiting is one of the most common traps for DIY migration scripts. Intercom's native S3 exports also do not include conversation transcripts — to get the actual messages, you must use the REST API, forcing you to navigate these exact rate limits.

Freshdesk enforces account-wide limits plus per-endpoint sub-limits. On Growth plans, ticket creation is capped at 80 requests per minute.

For a deeper look at how AI-generated migration scripts specifically fail at these constraints, see why DIY AI scripts fail at data migration.

Authentication and Credential Failures

Authentication failures mid-migration are among the most common causes of a script stalling silently — no loud crash, just requests that start returning 401 Unauthorized or 403 Forbidden after the migration has already been running for hours.

OAuth token expiry. If you are authenticating via OAuth, access tokens have finite lifespans — typically 1–2 hours. A migration script that starts successfully and then begins failing partway through is often hitting token expiry. Your script must implement automatic token refresh before the access token expires. Do not assume a token that worked at 9 AM will still work at 11 AM.

API key rotation. If your organization rotates API keys on a schedule or a security policy triggers a key revocation mid-migration, every subsequent API call will fail with a 401. Check your key rotation policy before starting a migration and lock the key for the duration of the run.

IP allowlisting. Some enterprise helpdesk configurations restrict API access to a whitelist of known IP addresses. If your migration script runs from a cloud runner (a CI/CD pipeline, a serverless function, or a dynamically provisioned VM), the outbound IP may not be on the allowlist. Every request will return 403 Forbidden — and a generic firewall rejection often looks identical to a permission error in the logs. Confirm the execution environment's outbound IPs are allowlisted on both the source and target platforms before starting.

Structural Mismatches Between Platforms

Zendesk organizes data around tickets with discrete comments, side conversations, and audit trails. Intercom organizes around conversations with flat message parts. Freshdesk has its own object model with different attachment size limits and no native equivalent for Zendesk side conversations.

When a migration tool encounters an object that has no 1:1 mapping in the destination platform, it either drops the data or silently truncates it. This is not a bug — it is a design gap. A migration can report 100% ticket-count parity while missing 10–15% of the actual content agents need.

Zendesk side conversations are a specific example: if your source system has side conversations and the target is Intercom or Freshdesk, there is no native equivalent object. The recommended mitigation is to convert each side conversation thread into an internal note on the parent ticket before or during migration, preserving the content even if the structural relationship is lost. This is a lossy conversion — the threading is gone — but it is preferable to silent data loss.

Missing Contact Dependencies

Helpdesk data is highly relational. A single ticket depends on a user record, an organization record, tags, custom fields, and attachments. If the contacts associated with your tickets are missing, corrupted, or out of sync, the ticket import will fail or stall.

Zendesk's Ticket Import API rejects tickets where the requester does not exist as an active user. Intercom's migration documentation states every migrated ticket or conversation must be associated with an existing user or lead. (intercom.com) This means your user import must complete cleanly before ticket migration begins.

Native Import Tool Limitations

If you tried using a platform's built-in CSV importer, you likely hit a wall fast. Zendesk's native CSV import handles users and organizations only — it cannot import tickets at all. Tickets require the Ticket Import API. Even then, handling multi-comment threads, inline attachments, and historical timestamps requires careful API orchestration that CSV files cannot express. A CSV import flattens your support history into a single text block stamped with today's date.

Automated tools like Import2 process at an average speed of ~50,000 tickets per day and do not support the import of agent profiles, macros, or saved replies. For straightforward migrations this works. For complex recoveries with partial data already in the target, it is not enough.

Intercom's own import tutorial notes that DIY API work is attractive for flexibility and cost control, but warns that large migrations need changes beyond the sample code. (developers.intercom.com)

Run a Sandbox & Sample Migration

Before you attempt to fix or resume the full migration, validate your approach in a safe environment.

Set Up an Isolated Sandbox

Most helpdesk platforms offer sandbox or trial instances. Create one. If your target is Zendesk, spin up a Zendesk Sandbox (available on Enterprise plans). For Freshdesk, use a free trial instance. For Intercom, create a test workspace.

Intercom's migration guidance explicitly calls for batch testing on a subset before the initial run, and that pattern is sound: fix mapping logic where failure is cheap, not after thousands of live records are wrong. (intercom.com)

What to Validate

Your sandbox migration should test for these specific behaviors:

• Thread direction and timestamps. Did the comments import in the correct chronological order? Do they retain their original creation dates, or did the API stamp them with the time of the import? Zendesk's Ticket Import API accepts created_at, updated_at, solved_at, and comment-level created_at. If you omit these, the record defaults to the import time. (developer.zendesk.com)
• Inline image rendering. Did the inline images transfer? If the source system requires authentication to view attachments, your script must download the image, upload it to the target, and rewrite the HTML <img> tags in the ticket body.
• Attachment integrity. Do PDFs, CSVs, and images download correctly? Check for size limits on the target platform.
• Public vs. private visibility. Verify that internal notes remained private and public replies show as customer-facing. A single mapping error here can expose internal communications to customers.
• Relational integrity. Is the ticket correctly assigned to the right user and organization? If a contact was missing, did the script fail or assign the ticket to a fallback user?

Sample Size That Actually Catches Problems

Do not test with 5 tickets. Use a minimum of 100 tickets selected across these categories:

• Tickets with 10+ comments (tests thread depth)
• Tickets with inline images in the body (tests HTML sanitization)
• Tickets with attachments >5MB (tests size limits on the target)
• Tickets in every status (open, pending, solved, closed)
• Tickets assigned to agents who no longer exist (tests edge-case handling)
• Tickets with nested custom fields and multiple tags
• Merged tickets and tickets with deleted users

Your sample set should be deliberately ugly. If a scenario exists in production, it needs to exist in the sample. Help Desk Data Migration's demo guidance also notes that failed records often come down to missing contact data or inactive agents. (help-desk-migration.com)

Maintain a Crosswalk Table

For every test run, keep a mapping between source and target IDs:

source_ticket_id     -> target_ticket_id
source_contact_id    -> target_contact_id
source_comment_id    -> target_comment_id or ordinal
source_attachment_id -> target_attachment_id
migration_batch_id   -> rollback/retry scope

A sample run is successful only if it is repeatable. Counts must match, authors and public/private direction must be correct, attachments must open, and a second run must not create duplicates. If you do not have idempotency yet, you do not have a rescue plan.

How to Capture In-Flight Data (Delta Migration)

While your migration was failing or stalled, your support team kept working. Customers kept submitting tickets. Agents kept replying. That in-flight activity exists in the source system but not in the target, and it needs to come across without creating duplicates.

Delta migration captures only the records created or updated since a specific timestamp — typically the moment your original migration began.

How It Works

1. Identify your cutoff timestamp. Find the exact Unix timestamp of the last successful record extracted before the crash, or use the start_time of your original migration run.

2. Use incremental export APIs. Zendesk's Incremental Exports API supports cursor-based pagination and returns only items changed since your start_time:

GET /api/v2/incremental/tickets/cursor?start_time=<unix_time>
GET /api/v2/incremental/ticket_events?start_time=<unix_time>&include=comment_events

In Zendesk, the initial start_time must be at least one minute in the past, and both ticket and ticket-event exports omit the most recent minute to avoid race conditions. If you need full comment bodies in the event stream, use include=comment_events. (developer.zendesk.com) Intercom's conversation search can be filtered by updated_after.

For Freshdesk, use the tickets list endpoint with the updated_since filter parameter to retrieve tickets modified after your cutoff timestamp:

GET /api/v2/tickets?updated_since=<ISO8601_timestamp>&order_by=updated_at&order_type=asc

Freshdesk paginates at 30 tickets per page by default (maximum 100 with per_page=100). On Growth plans, the ticket list endpoint shares the account-wide rate limit cap — factor this into your backoff logic when iterating through large delta windows.

3. Deduplicate against the target. Before importing delta records, cross-reference against what already exists in the target system by source ticket ID or external ID. Your script must use upserts (update if exists, insert if not) rather than blind inserts. This ensures that if a ticket was partially migrated during the crash, the delta sync will overwrite it with the complete record instead of creating a duplicate.

4. Repeat until the delta window is small enough to cut over safely.

Pause notifications while the delta runs. Intercom explicitly tells teams to turn off email notifications for historical ticket imports. Zendesk imported tickets do not run triggers, but surrounding integrations or webhook-based syncs can still fire if you do not isolate them. (developers.intercom.com)

For the full pattern behind keeping support running during a migration, see zero-downtime help desk migration.

Timeline Reality Check

The longer the gap, the more complex the delta. If your source system accumulated a week of activity, you are not patching — you are running a second migration.

Validation & Reconciliation Checklist

After completing the rescue migration (sandbox-validated, delta-inclusive), run these checks before declaring victory. Do not rely on ticket counts alone — a script can successfully create 10,000 tickets while silently dropping every attachment.

Record Counts

• Total ticket count in target matches source (within migration scope)
• Total user/contact count matches
• Organization count matches
• Knowledge base article count matches (if migrated)

Compare counts by slice, not just totals. Break down by status, created month, team or group, and inbox or brand.

Content Integrity

• Thread depth: Open 20+ high-comment tickets and verify all comments appear in correct chronological order
• Inline images: Confirm screenshots and embedded images render (not just show as broken <img> tags)
• Attachments: Spot-check that PDFs, CSVs, and images download correctly. Zendesk drops attachments larger than 50 MB. (support.zendesk.com)
• Private vs. public: Verify internal notes did not flip to public-facing replies
• Author mapping: Verify that internal notes are attributed to the correct agents, not the API admin account that ran the script

Metadata Accuracy

• Timestamps: created_at and updated_at match source values
• Assignees: Tickets assigned to the correct agents and groups
• Custom fields: Dropdown values, text fields, and checkboxes transferred correctly
• Tags: All source tags present on target tickets
• Statuses: Open/pending/solved/closed map correctly (watch for platforms that do not support all states)

Relationship Integrity

• Requester → ticket: Every ticket has a valid requester
• Organization → user: Org memberships intact
• Parent → child tickets: If using linked or child tickets, verify relationships

Operational Object Parity

• Macros, saved replies, and triggers migrated where applicable. Import2 does not import agent profiles, macros, or saved replies into Zendesk. (import2.com)
• Workflow triggers: Confirm migrated tickets did not accidentally trigger automations (e.g., sending thousands of old satisfaction surveys to customers)
• Searchability: Agents can find migrated tickets by requester email, old ticket ID, and external ID during the first weeks after cutover

For the full 20-test QA suite, see our post-migration QA checklist.

Rollback vs. Continue: The Decision Framework

This is the hardest call. Here is a framework.

Choose ROLLBACK when:

• More than 30% of tickets have content-level issues (missing comments, broken attachments, wrong timestamps)
• Your target system has been actively used by agents for less than 48 hours (minimal new data to lose)
• The root cause is a fundamental mapping error that affects every record (e.g., all internal notes migrated as public)
• You used a native CSV importer and lost all thread history and timestamps
• The effort to write a script that patches the missing fields exceeds the effort of a clean re-migration

Choose CONTINUE + PATCH when:

• Fewer than 10% of tickets have issues, and the issues are identifiable and patchable
• Agents have been working in the new system for 3+ days (significant new data exists only in the target)
• The failure was a hard stop (e.g., a 429 rate limit crash) rather than silent data corruption — you know exactly which ticket ID failed
• The target platform supports idempotent upserts, allowing you to safely re-run without duplicating records
• You have a validated sandbox run proving the fix works

The gray zone (10–30% issues): The deciding factor is whether agents have started using the target system. If yes, rolling back means losing their recent work — that is often worse than patching. If no, roll back and do it right.

Be especially careful with attachment-heavy recoveries. In Zendesk, attachments are bound to new comments via single-use upload tokens and cannot be added to an existing comment after the fact. If historical attachment placement matters, rollback is often safer than trying to surgically repair in place. (developer.zendesk.com)

How to Measure Your Issue Rate

The thresholds above (10%, 30%) are only useful if you can actually calculate your issue rate. Here is how to do it from migration logs:

1. Pull your migration log file. Your script should have logged every API response — specifically the HTTP status code and the source record ID for each request.
2. Count total attempted records. This is the denominator. Filter your log for all records the script attempted to create or update in the target (i.e., all POST or PUT requests to the tickets endpoint).
3. Count failed records. Filter for responses that returned 4xx or 5xx status codes, or for records where the target ID was never written back to your crosswalk table.
4. Calculate issue rate: failed_records / total_attempted_records * 100.
5. Spot-check a sample of successful records for silent failures. A 201 Created response confirms the ticket exists in the target — it does not confirm that the content is correct. Pull 50 randomly sampled tickets from the target and compare them field-by-field against the source records using your crosswalk table.

If your script did not log individual response codes per record, you cannot calculate an accurate issue rate. In that case, treat the situation as the gray zone and run a manual spot-check of at least 200 tickets across statuses and date ranges before deciding.

How to Roll Back

If you choose rollback:

1. Re-route all channels (email forwarding, chat, phone) back to the source system
2. Notify agents and set a clear "we are back on the old system" timestamp
3. Delete or archive the partially-imported data in the target — do not leave ghost records
4. Review and fix the root cause before attempting again
5. Run a fresh validated sandbox migration before scheduling the next attempt

Check deletion semantics before you promise a rollback window. Not all migrated data can always be deleted cleanly from every platform. (help-desk-migration.com)

Data Residency and Compliance During Recovery

A failed migration leaves you in a state most compliance frameworks do not anticipate: live customer data sitting simultaneously in two systems, with no clean boundary between which is authoritative.

Three issues to address before recovery is declared complete:

Dual-system data residency. If your organization operates under GDPR or CCPA, data subjects have the right to deletion and data portability. While recovery is in progress, the same personal data exists in both the source and target. Document this window explicitly — start date, end date, and which system was authoritative at each point — in your incident log. This documentation matters if a data subject submits a deletion request during recovery.

Deletion confirmation after rollback. If you roll back and purge partially-migrated records from the target, verify that the deletion is complete. Some platforms soft-delete records and retain them in internal storage for a grace period. Confirm with your target platform's documentation that a deleted contact or ticket is fully removed, not just hidden from the UI, before you close the compliance window.

Audit log continuity. Enterprise helpdesk platforms typically maintain audit logs of all ticket activity. If your migration script created, modified, or deleted records via API, those actions will appear in the audit log under the API admin account that ran the script. Preserve these logs. If you need to demonstrate to an auditor what changed and when, the audit log is your primary evidence.

For a deeper treatment of GDPR and CCPA considerations in migration projects, see our GDPR compliant data migration guide.

When to Request a Managed Rescue

DIY recovery makes sense when the failure is contained — a few hundred missing attachments, a custom field mapping that needs adjustment, a rate-limit issue you can solve with better backoff logic.

But some situations call for a team that has done this before:

• You have attempted recovery twice and the same issues recur. Repeating the same approach without changing the underlying architecture will produce the same result.
• The volume exceeds what your team can validate manually. Spot-checking 20 tickets out of 200,000 is not validation — it is hope. Reconciliation at scale requires automated diff tooling.
• You are hitting platform-specific edge cases — multipart attachment uploads, HTML sanitization quirks, undocumented API behaviors — that your team has not encountered before.
• Live support cannot pause and you need delta-based recovery rather than a hard freeze.
• Source exports are incomplete and you need API-based rehydration of threads or comments.
• Compliance or audit requirements mean approximate history is not good enough.

ClonePartner's engineers write custom scripts tailored to the exact source and target schemas, handle the undocumented edge cases (rate-limit windowing, inline image re-hosting, side conversation conversion), and run continuous delta syncs so your support team never has to stop working.

Estimated Recovery Timelines

These assume the source system is still accessible and a backup exists. If the source system has been decommissioned or the backup is incomplete, add time for data reconstruction.

Timelines stretch fast when APIs are tight. Zendesk incremental exports are capped at 10 requests per minute unless you have the High Volume add-on, and Import2 documents an average Zendesk migration speed of around 50,000 tickets per day. (developer.zendesk.com)

Post-Recovery Monitoring: The First 7 Days

A rescue migration that passes all reconciliation checks is not done — it is in observation. The first week after cutover surfaces problems that static validation cannot catch: agents working in the system at scale, edge-case tickets surfacing in search, and SLA-sensitive workflows hitting unexpected states.

Watch for these specific issues in the 7 days following a rescue migration:

Search gaps. Migrated tickets may not be immediately indexed in the target platform's search. Agents reporting that old tickets are "missing" are often finding real records that have not yet been indexed. Most platforms complete full-text indexing within 24–48 hours of import. If tickets remain unsearchable after 48 hours, contact the target platform's support — this is a known edge case with bulk API imports.

SLA timer anomalies. Zendesk notes that imported tickets do not bring in ticket metrics like first reply time. If your SLA reporting depends on these fields, migrated historical tickets will show anomalous or missing SLA data. Decide before go-live whether historical SLA data needs to be preserved and document the gap for your support operations team.

Broken ticket references. Agents who bookmarked or hard-linked specific tickets in the old system will find those URLs no longer work. If you maintained a crosswalk table mapping source ticket IDs to target ticket IDs, publish it as an internal reference so agents can resolve old IDs manually.

Attachment access errors. Agents opening tickets with attachments may encounter access errors if the attachment hosting URL requires re-authentication or if tokens have expired. Spot-check a fresh sample of attachment-heavy tickets on days 2 and 5 after go-live, not just immediately after migration.

Duplicate ticket reports. If the delta migration ran while agents were also manually re-entering tickets they thought were lost, you may have duplicates that only surface when agents search by customer email. Run a duplicate-detection query on requester email + subject line during the first 48 hours.

Webhook and integration re-firing. Third-party integrations connected to the target platform — CRM syncs, reporting tools, billing triggers — may re-process migrated historical tickets as "new" events when they see the imported records for the first time. Audit your active integrations before go-live and disable any that should not trigger on historical data.

What to Do Next

If your migration just failed, here is the priority stack:

1. Right now: Run through the Emergency Triage Checklist above
2. Within 2 hours: Identify the root cause category (rate limits, authentication failure, structural mismatch, missing dependencies, tool limitation)
3. Within 4 hours: Decide rollback vs. continue based on the decision framework
4. Within 24 hours: Execute the rollback or begin a sandbox-validated recovery run
5. Within 48 hours: If recovery is not converging, get outside help before the problem compounds

The longer a partially-migrated system sits in production, the harder it gets to fix. Every new ticket created in the target is data that will not exist in the source. Every reply an agent makes in the old system is data that will not exist in the target. The drift accelerates daily.