Error reference

#The shape of an error

Every error under /v1 is JSON, never an HTML page:

{ "error": "slug already exists in this workspace" }

Some errors add fields: message (a sentence you can show to a person), reason (which limit or check), limit, resetsAt, hint or upgradeUrl. When error is a single snake_case word it's a stable code you can branch on; the table below lists every one. Any other error is a plain-English sentence: show it or log it, but don't match on its exact wording, because it can change.

#What each status means

#Machine-readable codes

Plan limits answer 402 with the database's sentence in error, a reason and an upgradeUrl:

Your existing links keep redirecting whatever the plan limit; only new links and webhooks wait. Plans and their limits are on Pricing.

#Every error, by status

The list below is generated from the server's source, so it's exactly what the API can send. … stands for a value filled in at the time (a number, a name or a list). Field checks that build their message from what you sent (a slug, a hostname, a date) aren't listed one by one; they're all 400. Errors that only the dashboard can get (billing, the Firebase import) are left out.

#400 Bad request

• country must be a 2-letter country code (ISO 3166-1, e.g. IN)
• destination_blocked
• deviceId required: the SDK debug device id (8–64 letters, digits, - or _)
• expiresAt must be epoch milliseconds, an ISO 8601 date-time, or null
• from / to must be ISO dates (e.g. 2026-01-31) or epoch ms
• invalid cursor
• invalid_domain
• invalid_idempotency_key
• invalid_report
• invalid_url
• isActive must be true or false
• limit must be 1 to 100
• limit must be an integer from 1 to 100
• linkId + device fields required
• linkId required
• links must be an array of 1 to … links
• longUrl must be https
• malformed JSON body
• part must be one of …
• platform + device fields required
• platform must be 'android' or 'ios'
• refused
• send isActive on its own, then other fields in a second request
• slug ([a-zA-Z0-9_-], ≤64) and https longUrl are required
• status must be active or paused
• tenantId is required with the admin key
• tenantId required
• token must be a Strait handoff token (22 base64url characters)
• token was issued for another part
• type the workspace link handle exactly to confirm
• ua required: a preset (…) or a raw user agent
• unknown linkId
• url must be a full short link, e.g. https://…/your-slug
• url must be a full short link, e.g. https://you.strait.link/summer

#401 Unauthorized

• analytics needs a secret key (Authorization: Bearer st_live_…); publishable keys only work for the SDK endpoints
• download link expired or already used — start the download again
• invalid API key
• invalid publishable key
• invalid secret key
• publishable key required (find it in Dashboard → Get started)
• secret key (Authorization: Bearer st_live_…) or publishableKey required
• secret key or dashboard session required (Authorization: Bearer …)
• secret key required (Authorization: Bearer st_live_…)
• session expired — sign in again
• sign in to the dashboard to close a workspace (a key cannot)
• the referral report needs a secret key (Authorization: Bearer st_live_…)
• unauthorized

#402 Payment required

• plan_required
• (plan limit, reason: "clicks", message from the database)
• (plan limit, reason: "links", message from the database)
• (plan limit, reason: "webhooks", message from the database)

#403 Forbidden

• fresh_mfa_required
• key_scope
• mfa_required
• not a member of this workspace
• only an owner can close this workspace
• only owners and admins can export (an export contains all workspace data)
• viewers cannot add domains
• viewers cannot create links
• viewers cannot redeliver webhooks
• viewers cannot remove domains
• viewers cannot see webhook deliveries

#404 Not found

• delivery not found
• domain not found
• link not found
• no active link "…" in this workspace
• no such link in this workspace
• not a trace token
• not configured
• not found
• webhook not found
• workspace not found

#409 Conflict

• A workspace can have up to … custom domains. Remove one first.
• already delivered
• cancel your paid plan in Plan & usage first, then close the workspace
• idempotency_key_in_use
• link_blocked
• slug already exists in this workspace
• slug_in_use
• this delivery is being sent right now — try again in … minutes
• This domain is already added to a Strait workspace.
• this old link (legacyHost + legacyCode) is already imported in this workspace
• your payment is still being confirmed — open Plan & usage in a minute, cancel the plan there, then close the workspace

#413 Payload too large

• request body too large

#421 Misdirected request

• Use https://strait.link (or your link domain); this origin only answers Strait's edge.

#422 Unprocessable

• dns_failed
• idempotency_key_reused

#429 Too many requests

• busy
• new_account_limit
• QR rendering is busy: try again in a few seconds, or ask for format=svg
• rate limited
• rate limited: at most 30 analytics calls a minute per workspace
• rate limited: at most 30 referral report calls a minute per workspace
• rate limited: at most 30 usage calls a minute per workspace
• rate limited: at most 60 QR codes a minute per workspace
• rate limited: domain status is checked at most every few seconds
• rate_limited
• Too many domain changes. Try again in a few minutes.

#500 Internal error

• internal error

#502 Bad gateway

• Couldn't remove the domain from our certificate provider. It's still listed; try again in a minute.
• Couldn't set up the domain with our certificate provider. Nothing was saved; try again in a minute.

#503 Unavailable

• domains_not_enabled
• domains_read_only

#Related

• REST API: every endpoint, with the statuses it answers.
• Rate limits: what answers 429, and when to try again.
• Webhooks: failed deliveries show HTTP <status>, timeout, unsafe_target or webhook_removed.