Importing thousands of links without breaking anything

Validate the source data before you send anything

Run the whole file through checks first: every destination is a well-formed absolute URL with a scheme, no slug appears twice, no slug uses characters your platform rejects, and no destination is itself a short link that will create a chain. Fixing these in a spreadsheet takes an hour. Fixing them after ten thousand links exist takes a week.

Decide the slug policy up front

You either preserve the original slugs, which is mandatory if the links are already published, or you generate new ones, which is only acceptable for links not yet in circulation. If preserving, expect collisions with links already in the destination workspace and decide in advance whether to fail, rename or skip. Silent renaming is the worst option because it breaks published links without telling anyone.

Import in batches with checkpoints

Process a few hundred at a time, record the outcome of every row to a file, and make the whole job resumable from the last checkpoint. A job that must restart from zero after an interruption will be interrupted at ninety percent, reliably, by the laws of the universe.

Respect rate limits deliberately, not reactively

Compute a safe request rate from the documented limit and stay under it rather than sprinting into 429s and backing off. A bulk import is not urgent by minutes; spreading it over an hour costs nothing and avoids being throttled at an unpredictable point.

Do a small pilot and verify it end to end

Import fifty links, then actually request each one and confirm it returns the expected destination. Automated verification of the pilot catches encoding problems, trailing whitespace in destinations and parameter mangling — the errors that are invisible in the API response and obvious to a visitor.

Reconcile after the full run

Compare the source list against what exists in the platform: count, slug set, and a sample of destinations fetched back from the API. Report the differences explicitly. An import that says it succeeded without a reconciliation step has not been verified, it has been assumed.

Keep the source file and the result log

Six months later someone will ask why a particular link points where it does. The import log answers that in seconds. It is also what you need if you ever move again, because the next migration starts from the same file.