Errors, status codes and how to handle them

Failures come back as JSON with a message written to be shown to a person. The status code tells you what kind of problem it is and whether retrying will help.

Codes you will see

• 400 — the request is wrong. A missing destination, an invalid URL, a slug containing characters that are not allowed, a reserved slug, an import with no rows. Fix the request; retrying is pointless.
• 401 — no valid credentials. The key is missing, malformed, revoked or expired.
• 402 — a plan limit is in the way. Returned by the conversions endpoint when the monthly conversion allowance is used up, with an upgrade flag on the body.
• 403 — authenticated but not allowed. A readonly member on a write endpoint, or a non-admin on billing, key management or domain deletion.
• 404 — not found, or deliberately hidden. A link restricted to named users returns 404 to everyone else so its existence is not disclosed.
• 409 — a conflict. A slug already used on the domain, or a duplicate destination on a domain that does not allow duplicates. The duplicate response includes the existing link so you can use it.
• 429 — rate limited. Back off and retry with increasing delay.
• 5xx — a server-side failure. Retry with backoff; if it persists, the delivery or job logs usually say more.

Partial success is not an error

Two cases return 200 while not doing everything you asked:

• Gated fields. A write containing Pro-only fields on a free plan succeeds with those fields dropped, and the response carries upgradeRequired naming them.
• Bulk operations. An import or a sheet apply returns counts of created, updated, deleted and failed rows plus per-row errors. A 200 here means the run completed, not that every row worked.

Check both. A client that treats 200 as complete success will quietly lose settings on a free plan and quietly lose rows on an import.

Writing a resilient client

• Retry only 429 and 5xx, with exponential backoff and a cap.
• Treat 409 on create as "fetch the existing link and use it".
• Log the message body — it names the specific limit, host restriction or validation rule that failed.
• Check for a blocked destination: a domain can restrict destinations to an allowed list, and links to hosts on the global abuse blocklist are refused outright.

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