Imports and API calls that fail

Bulk work fails per row rather than all at once, and the API tells you which rule was broken. Both give you enough to fix the input without guessing.

Imports

Always preview first. The preview shows the detected headers, the field each maps to, the row count and the first twenty rows, and lets you correct the mapping before anything is written. Most import problems are a header that was not recognised and silently ignored.

After a run, the job list shows created, updated, deleted and failed counts, and the failed rows can be downloaded as a CSV with the error attached to each. Fix those rows and re-import only them.

Common per-row failures:

• Slug already used on this domain. Two rows with the same slug, or a slug that already exists.
• That slug is reserved. Either globally, or on the domain's own reserved list.
• Destination URL is not valid. Usually a missing scheme or a stray space.
• Blocked destination. The host is on the abuse blocklist, or the domain restricts destinations to an allowed list.
• Unknown link id. In a sheet apply, an Id that does not belong to this organization.

Imports are capped at 10,000 rows per file. Split larger files.

The sheet

The sheet has three behaviours and they are decided by two columns: a row with an Id updates, a row without one and with a destination creates, and a row with 1 in Delete deletes. Deleting the Id column contents and re-uploading therefore creates duplicates rather than updating. Leave that column alone.

API failures

• 400 — the payload is wrong; the message names the field or rule.
• 401 — the key is missing, revoked or expired.
• 403 — your role cannot do this.
• 404 — not found, or a link restricted to other people.
• 409 — the slug is taken, or the destination already has a link on a domain that does not allow duplicates. The response includes the existing link.
• 429 — rate limited; back off.

Silent partial success

A 200 does not mean everything applied. Gated fields are stripped on plans that lack the feature, and the response carries upgradeRequired naming them. Bulk responses carry per-row errors. Check both.

Find this in your dashboard

1. Sign in and select the workspace and domain you want to manage.
2. Open Branded Links. Review the article’s steps and your plan’s available controls.
3. Save your changes, reopen the record and verify the saved result. For routing changes, check the short link with a test visit.

API workflow guides · Open dashboard