Troubleshooting

Solutions to common issues when integrating with the SnipLink API.

Authentication Issues

401 Unauthorized - Invalid or Missing API Key

Symptom: API returns AUTHENTICATION_REQUIRED or INVALID_API_KEY.

Common causes:

• Missing header: Ensure you include the X-API-Key header in all requests.
• Wrong header name: Use X-API-Key, not Authorization: Bearer.
• Revoked key: Check if the key was revoked in your dashboard.
• Expired key: API keys with expiration dates may have expired.

Correct format:

curl -X GET https://api.sniplink.co/v1/workspaces/{workspaceId}/links \
  -H "X-API-Key: snip_your_api_key_here"

403 Forbidden - Insufficient Permissions

Symptom: API returns INSUFFICIENT_PERMISSIONS.

Common causes:

• Missing scopes: Your API key doesn't have the required scopes for this operation.
• Wrong workspace: The API key belongs to a different workspace.
• Resource ownership: You're trying to access a resource that belongs to another workspace.

Solution: Create a new API key with the required scopes:

• links:read - Read link information
• links:write - Create, update, delete links
• analytics:read - View analytics data
• domains:read - Read domain information
• domains:write - Manage custom domains
• webhooks:read - View webhook configurations
• webhooks:write - Manage webhooks

Rate Limit Errors

429 Too Many Requests

Symptom: API returns RATE_LIMIT_EXCEEDED.

Understanding rate limits:

Response headers to monitor:

X-RateLimit-Limit: 60        # Maximum requests allowed
X-RateLimit-Remaining: 45    # Requests remaining in window
X-RateLimit-Reset: 1705312800 # Unix timestamp when limit resets
Retry-After: 30              # Seconds to wait (only on 429)

Best practices:

• Implement exponential backoff: When you receive a 429, wait and retry with increasing delays.
• Cache responses: Avoid repeated requests for the same data.
• Use bulk operations: Create multiple links in a single request when possible.
• Monitor headers: Track X-RateLimit-Remaining and slow down before hitting limits.

Password Verification Rate Limits

Password-protected link verification has stricter limits to prevent brute force attacks:

• 5 failed attempts triggers a 15-minute lockout
• Lockouts are per-link and per-IP combination
• Successful verification resets the counter

Webhook Delivery Problems

Webhooks Not Being Delivered

Common causes:

• Endpoint not reachable: Ensure your endpoint is publicly accessible (not localhost).
• SSL certificate issues: Your endpoint must have a valid SSL certificate.
• Firewall blocking: Allow incoming connections from SnipLink IP ranges.
• Webhook disabled: Check if the webhook was auto-disabled after repeated failures.

Webhook Signature Verification Failing

Symptom: Your signature verification rejects valid webhooks.

Correct verification process:

import crypto from 'crypto';

function verifyWebhookSignature(
  payload: string,
  signature: string,
  secret: string
): boolean {
  // Important: Use the raw request body as a string
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  const providedSignature = signature.replace('sha256=', '');

  // Use timing-safe comparison to prevent timing attacks
  return crypto.timingSafeEqual(
    Buffer.from(expectedSignature),
    Buffer.from(providedSignature)
  );
}

Common mistakes:

• Parsing before verification: Always verify the raw string body, not parsed JSON.
• Wrong secret: Ensure you're using the webhook signing secret, not your API key.
• Modified body: Some frameworks modify the body; use raw body middleware.

Webhook Delivery Exhausted

After 5 failed delivery attempts, webhooks are marked as exhausted. To retry:

1. Fix the underlying issue with your endpoint
2. Check webhook delivery logs in your dashboard
3. Re-enable the webhook or create a new one

Error Code Reference

Link Creation Issues

SLUG_TAKEN Error

Symptom: Cannot create a link with your desired slug.

Solutions:

• Choose a different slug
• Omit the slug field to get an auto-generated one
• Use a custom domain (slugs are unique per domain)

INVALID_URL Error

Symptom: The destination URL is rejected.

URL requirements:

• Must include protocol (http:// or https://)
• Must be a valid, reachable URL
• Cannot point to localhost or private IP ranges
• Cannot redirect to another SnipLink short link

PLAN_LIMIT_EXCEEDED

Symptom: Cannot create more links.

Plan limits:

• Free: 25 links/month
• Pro: 1,000 links/month
• Business: 10,000 links/month
• Enterprise: Unlimited

Limits reset on your billing cycle date. Check your usage in the dashboard.

Custom Domain Problems

Domain Verification Failing

Checklist:

1. Check DNS propagation: Use dnschecker.org to verify records are visible globally.
2. Verify TXT record format: Must be exactly sniplink-verify=YOUR_TOKEN with no extra characters.
3. Verify CNAME record: Must point to redirect.sniplink.co.
4. Wait and retry: DNS can take up to 48 hours (usually minutes).

SSL Certificate Not Working

Requirements:

• Domain must be verified first
• CNAME record must be correctly configured
• Allow 1-5 minutes for certificate provisioning

Links on Custom Domain Return 404

Possible causes:

• Domain is not verified or is disabled
• DNS CNAME record is incorrect or not propagated
• The specific link was deleted or expired
• Link was created on a different domain

Still Need Help?