Troubleshooting

This page covers common errors, authentication issues, and debugging approaches. For full error code definitions, see the individual error reference pages.

Authentication errors

401 Unauthorized

Cause: The API key is missing, invalid, or does not have access to the requested resource.

Fix:

• Verify your API key is included in every request as the apikey header
• Confirm you are using the correct header name: apikey (all lowercase), not Authorization or x-api-key
• Check that the API key has not been rotated or deleted at app.rebrandly.com/account/api-keys

# Correct
curl -H "apikey: YOUR_API_KEY" https://api.rebrandly.com/v1/links

# Incorrect — will return 401
curl -H "Authorization: Bearer YOUR_API_KEY" https://api.rebrandly.com/v1/links

Exception: The search endpoint (/v1/links/search) uses Authorization: Bearer YOUR_TOKEN (OAuth access token), not the apikey header. This is an inconsistency in the current API. See Searching links.

API key environment variable conflicts

If your API key is set in multiple places (project .env file, shell environment, MCP config), one will take precedence. Confirm which value is active if you receive unexpected 401 errors despite setting the key.

Rate limit errors

429 Too Many Requests

Cause: You have exceeded the request rate for your workspace type or plan.

Rate limits by workspace:

For high-volume link creation, each call creates up to 25 links—so 3,600 calls/hr represents up to 90,000 links/hr at max batch size.

Fix: Read the rate limit headers in the 429 response and wait before retrying:

async function requestWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.status !== 429) {
      return response;
    }

    // Read reset time from response header
    const resetHeader = response.headers.get("X-rate-limit-reset");
    const retryAfter = resetHeader
      ? parseInt(resetHeader, 10) * 1000 - Date.now()
      : 1000 * Math.pow(2, attempt); // exponential backoff fallback

    console.warn(`Rate limited. Retrying in ${Math.ceil(retryAfter / 1000)}s`);
    await new Promise(r => setTimeout(r, Math.max(retryAfter, 0)));
  }

  throw new Error("Max retries exceeded after rate limiting");
}

Rate limit headers:

Access and permissions errors

403 Forbidden

Cause (standard): Your API key does not have permission for this operation, or you have reached a plan limit.

Cause (high-volume API WAF): If you are sending a POST body containing HTML <script> tags to enterprise-api.rebrandly.com, the WAF returns a 403 as an HTML response, not JSON. This affects /v1/scripts (retargeting script creation).

Fix for WAF 403: Use api.rebrandly.com instead of enterprise-api.rebrandly.com for /v1/scripts requests. See High-volume API: hosts and routing.

Fix for plan limit 403: Check your usage at app.rebrandly.com/account/api or via GET /v1/account (subscription.limits).

Not found errors

404 Not Found

Cause: The requested resource does not exist, or the endpoint path is wrong.

Common causes:

• Using a high-volume API link id with a sub-resource endpoint (e.g. /v1/links/{id}/rules). Sub-resource endpoints are not supported on high-volume API links. See High-volume API link limitations.
• Requesting a link that has expired (high-volume links with a past expiresAt)
• Typo in the endpoint path

High-volume link issues

Field has no effect after a 200 OK

Cause: Some fields are accepted by the API but silently dropped at the persistence layer for high-volume links. The request succeeds (200 OK) but the behavior has no effect.

Affected fields: tags, password, OpenGraph metadata, description, title (link notes). See High-volume API link limitations for the full list.

Sub-resource endpoint returns 500

Cause: You are using a per-link sub-resource endpoint (e.g. /v1/links/{id}/rules, /v1/links/{id}/apps) with a high-volume link ID. These endpoints are not supported for high-volume links.

Fix: Traffic routing, native routing, retargeting scripts, and tags must be applied at creation time using inline fields on POST or PUT /v1/links—and some are not supported at all for high-volume links.

Server errors

500–504 Server Errors

Server errors indicate an issue on Rebrandly's side. These are typically transient.

Fix: Implement exponential backoff and retry logic (see 429 example above). If the error persists, check Rebrandly status and contact support.

Webhook and Clickstream issues

Endpoint not receiving events

Cause: Clickstream webhook delivery is provisioned by Rebrandly — it does not self-activate after configuration. If your endpoint is not receiving events, the integration may not yet be active.

Fix:

• Confirm with your Rebrandly account team that the integration has been activated
• Verify your endpoint is publicly accessible and accepts POST or PUT requests
• Check that your endpoint returns a 2xx response — non-2xx responses are treated as delivery failures

Authentication failures

Cause: Each Clickstream payload includes a key field for authenticating incoming events. If your endpoint is rejecting requests, the key value may be misconfigured.

Fix: Confirm the key value in the incoming payload matches the authentication header value provided during setup. Contact your Rebrandly account team if the key needs to be rotated.

Events not appearing for high-volume links

Cause: Clickstream covers click events for all workspace types. If you are not seeing events for links created via the high-volume API, the issue is likely with endpoint availability or delivery failure, not workspace type.

Missing event types

Clickstream delivers click events only. Link creation, link deletion, and TTL expiry do not generate Clickstream events for any workspace type.

See also: Clickstream overview, Clickstream webhook setup

Still stuck?

• API reference—endpoint documentation
• Error codes—HTTP response reference, with individual pages per error code
• Contact support—for account-specific issues