Troubleshooting

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›Organization›Domains and check the status of your domain. It must show Ready, not Pending, Verified, 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. 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:

1. Open your domain under Settings›Organization›Domains and find the DNS setup panel. The key record is the traffic routing (CNAME / ALIAS) record-verification cannot complete without it. The panel also tracks the TXT (domain ownership) and SSL certificate steps, which usually complete automatically; a TXT record is only required when the panel lists one.
2. Confirm the routing record points at the exact target shown in the panel, and that any listed TXT record uses the exact Record name and Record value shown. Copy them-do not retype.
3. Verify the records are visible using a DNS tool:

   dig CNAME <your hostname>
   

   Or check at dnschecker.org. Each record should return the exact value from your Nimriz dashboard.
4. If the records are visible but verification still fails, confirm the values have no extra spaces, missing characters, or encoding differences, then click Check now to force an immediate re-check. Records checked before they existed can stay hidden from some resolvers for up to 30 minutes.
5. If you are using Cloudflare, confirm the records are set to DNS only (grey cloud). Proxied records hide where your hostname points and are not visible to external DNS queries.
6. Steps that already show Verified or Certificate issued are complete; their TXT records are no longer needed and can be removed.

Verified but not reaching Ready:

After DNS verification, Nimriz activates the hostname at the Cloudflare edge (this provisions SSL and routes traffic). While this runs, the DNS setup panel shows Provisioning SSL; it typically takes a few minutes. If the domain remains in Verified status for more than 30 minutes:

• Click Check now on the DNS setup panel to refresh the activation status.
• Contact support with your domain name and workspace ID.

---

Cannot create a link

If the link creation form or API returns an error:

---

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.

1. Open the link's routing rules panel.
2. Look for any rule with no conditions-this matches all visitors. If it is above a more specific rule, move it below.
3. Confirm the specific rule for the affected country/device/OS combination is enabled (not greyed out as disabled).
4. Use the Preview routing 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 card on the domain (open it under Settings›Organization›Domains). It must show Ready-not Needs app metadata, Needs domain readiness, Locked, or Unsupported.
• Confirm the app metadata saved in the domain's Mobile app section is complete: iOS bundle ID + Team ID, and/or Android package name + SHA-256 signing fingerprint. The Deep link readiness card lists the saved apps and their status.
• 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:

1. Wrong password-confirm with the visitor that they are using the exact current password. Passwords are case-sensitive.
2. Password recently changed-after a password change, every new unlock requires the new password; the visitor may still be entering the old one. (Visitors who unlocked before the change keep access until their existing unlock cookie expires-up to 12 hours.)
3. Cookies blocked-the unlock mechanism depends on the browser accepting a cookie. Ask the visitor to confirm cookies are enabled and not being blocked by browser settings or extensions.
4. 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.
5. Different link-unlocks are link-specific. Unlocking one protected link does not unlock any other protected link, even on the same domain; each requires its own unlock.

---

Analytics look missing or delayed

1. 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.
2. Use Realtime - open Realtime for the link to see if events are arriving in real time. If Realtime shows recent clicks but your reports do not, you are experiencing normal aggregation lag. Wait for the next sync cycle.
3. No events in Realtime 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.
4. Strict privacy: if your workspace, the specific link, or your organization uses strict privacy, 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

---

Related guides

• Link creation and slugs
• Domains and DNS
• DNS verification
• Routing rules and preview
• Password-protected links
• Rate limits and errors