Troubleshooting

Diagnose redirects, domains, routing, password, analytics, and API issues step by step.

Before you start troubleshooting

Collect the following before diving into any issue. Having this information ready will help you isolate the problem faster and will be essential if you need to contact support.

The exact short URL you are testing (e.g., https://links.example.com/my-slug).
The expected destination URL.
The workspace and domain involved.
The exact time of the failing test.
Any error codes or support_reference strings shown in the dashboard or API response.
Whether routing rules or deep links are enabled for the link.

Redirect goes to a fallback page instead of the destination

When a short link hits a fallback (not-found, expired, or root landing) instead of the destination:

Step 1-Confirm the domain is correct

Open your short link in a browser. Note the exact hostname in the address bar.
Compare it to the domain configured in your Nimriz workspace. Hostname matching is strict-links.example.com and www.links.example.com are different domains. Even a minor mismatch results in a not-found fallback.

Step 2-Confirm the domain is Ready

Go to Settings → Domains and check the status of your domain. It must show Ready, not Verified, Pending, or Disabled.
A domain can complete DNS verification but not yet be activated at the Cloudflare edge. Both steps are required.

Step 3-Confirm the link is active

Find the link in your dashboard. Confirm the status is Active.
Check the expiration date. If the link has expired, visitors are routed to the domain's expired landing URL instead of the destination.
If the link is disabled, it will not redirect.

Step 4-Confirm the slug

Check that the slug in your short URL exactly matches what is saved on the link. Slugs are case-sensitive on some domains. A mismatch-even one character-will hit the not-found fallback.

If only one link is affected, it is likely a link-level issue (steps 3–4). If all links on the same domain are affected, it is likely a domain-level issue (steps 1–2).

Custom domain will not verify or reach Ready status

DNS verification stuck in Pending:

Confirm you published the TXT verification record at the correct hostname. The record name must be _nimriz-verify.<your-short-hostname>. For example, if your short domain is links.example.com, the record name is _nimriz-verify.links.example.com, not _nimriz-verify.example.com.
Verify the record is visible using a DNS tool:
```
dig TXT _nimriz-verify.links.example.com
```
Or check at dnschecker.org. The record should return the exact value from your Nimriz dashboard.
If the record is visible but verification still fails, confirm the value has no extra spaces, missing characters, or encoding differences.
If you are using Cloudflare, confirm the TXT record is set to DNS only (grey cloud). Proxied TXT records are not visible to external DNS queries.

Verified but not reaching Ready:

After DNS verification, Nimriz needs to activate the hostname at the Cloudflare edge (this provisions SSL and routes traffic). This typically takes a few minutes. If the domain remains in Verified status for more than 30 minutes:

Confirm the CNAME record pointing your hostname to Nimriz's edge is published and propagated.
Contact support with your domain name and workspace ID.

Cannot create a link

If the link creation form or API returns an error:

Symptom	Likely cause	Fix
Slug is rejected as reserved	System path (`admin`, `api`, `login`, etc.) or below the minimum length for the domain.	Choose a longer or different slug.
Slug is rejected as unavailable	Slug is taken, or was recently deleted and is in a temporary block window.	Wait or try a different slug.
Destination is rejected	URL uses a forbidden protocol (`javascript:`, `data:`, `file:`), or points to a Nimriz-managed domain.	Use a valid `https://` destination.
`expiration_required`	The domain or plan requires every link to have an expiration date.	Set a valid `expires_at` in the future.
`monthly_quota_exceeded`	Your workspace has reached its monthly link-creation limit.	Wait for quota reset or upgrade your plan.
`domain_disabled`	The selected domain is not active.	Check domain status in Settings → Domains.
`custom_domain_not_ready`	The custom domain is not yet Ready (still pending or only verified).	Wait for domain activation or check DNS setup.

Routing rule sends traffic to the wrong destination

Check rule order first. Rules are evaluated top to bottom-the first matching enabled rule wins. A broad catch-all rule near the top of your list will intercept traffic before more specific rules below it.

Open the link's routing rules panel.
Look for any rule with no conditions-this matches all visitors. If it is above a more specific rule, move it below.
Confirm the specific rule for the affected country/device/OS combination is enabled (not greyed out as disabled).
Use the routing preview / simulator to simulate the visitor's country, device OS, and device type. The simulator will show you exactly which rule Nimriz would apply.

Deep link routing not working:

Confirm the domain is a verified, ready, account-exclusive custom branded domain.
Check the deep link readiness indicator in your domain settings. It must show Ready, not Ineligible or Unconfigured.
Confirm the iOS or Android app-link metadata is fully complete (bundle ID, team ID, package name, etc.) in your domain configuration.
Visit https://yourdomain.com/.well-known/apple-app-site-association and https://yourdomain.com/.well-known/assetlinks.json directly in a browser. These must return valid JSON, not a 404.

Password-protected link keeps showing the password prompt

A visitor who keeps seeing the password prompt after entering the correct password:

Wrong password-confirm with the visitor that they are using the exact current password. Passwords are case-sensitive.
Password recently changed-if a workspace admin changed the password, all existing unlock cookies for the old password are immediately invalidated. The visitor must enter the new password.
Cookies blocked-the unlock mechanism depends on the browser accepting a session cookie. Ask the visitor to confirm cookies are enabled and not being blocked by browser settings or extensions.
Private/Incognito mode-cookies do not persist across private browsing sessions. The visitor will need to re-enter the password each time they open a new private window.
Different link-if the visitor bookmarked a different protected link on the same domain, it has its own independent cookie. Each link requires its own separate unlock.

Analytics look missing or delayed

Normal reporting lag-dashboard report rollups are updated on a schedule, not in real time. Allow up to several minutes for clicks to appear in your totals.
Use Live View-open Live View for the link to see if events are arriving in real time. If Live View shows recent clicks but your reports do not, you are experiencing normal aggregation lag. Wait for the next sync cycle.
No events in Live View either-confirm the redirect is being handled by the Nimriz edge (not a cached redirect served by a CDN in front of Nimriz). Confirm the link's domain is active and the redirect is actually happening.
Strict privacy-if your workspace, the specific link, or your organization uses strict privacy mode, unique click metrics are unavailable. Aggregate clicks should still be visible.

API errors and integration issues

401 Unauthorized

Confirm your Authorization: Bearer <key> or X-Nim-Api-Key: <key> header is correctly formatted.
Confirm the API key is for the correct workspace and has not been revoked.

403 or permission errors

The API key may belong to a workspace that does not have access to the requested domain.
The requested operation may require a plan feature that is not enabled for your workspace.

429 Too Many Requests

You have exceeded the API rate limit. Implement exponential backoff and retry.
For bulk link creation, use POST /api/shorten/bulk with stable idempotency_key values instead of individual rapid requests.

Conversion API signature rejected

Confirm you are using the Conversion API signing secret, not the workspace API key.
Confirm the signature is computed as HMAC-SHA256("${X-Nim-Timestamp}.${raw_request_body}", secret).
Confirm the X-Nim-Timestamp header is a recent Unix timestamp (in seconds, not milliseconds).
Confirm you are signing the raw request body bytes, not a re-serialized JSON object.

What to collect before contacting support

Information	Why it helps
Exact short URL tested	Confirms the host, slug, and domain.
Expected destination	Narrows whether it is a routing, expiration, or configuration issue.
Workspace and domain name	Helps support locate your configuration.
Time of the last failing test	Matches the event in server logs.
Error code or `support_reference` string	The support_reference directly identifies the specific failure in our system.
Screenshots of the UI or error	Visual context for dashboard or form issues.
Routing preview inputs and result	Essential for routing-rule debugging.
Whether routing rules or deep links are enabled	Narrows the evaluation scope.