Imported from jeremylongshore/tons-of-skills-marketplace (skills/.curated/linktree-common-errors/SKILL.md). Install upstream with npx skills add jeremylongshore/tons-of-skills-marketplace --skill linktree-common-errors. Copyright stays with the author (MIT).

Linktree Common Errors

Overview

Linktree's API manages link-in-bio profiles, individual links, appearance settings, and analytics. Common integration errors include URL validation failures when adding links with unsupported schemes, profile-not-found errors from incorrect username lookups, and analytics data lag that causes empty responses for recently created links. Analytics data lags 15-30 minutes behind real-time, which frequently causes confusion when verifying newly created links. This reference covers HTTP errors, link management issues, and analytics-specific quirks that affect Linktree API consumers.

Error Reference

Error Handler

interface LinktreeError {
  code: number;
  message: string;
  category: "auth" | "rate_limit" | "validation" | "not_found";
}

function classifyLinktreeError(status: number, body: string): LinktreeError {
  if (status === 401 || status === 403) {
    return { code: status, message: body, category: "auth" };
  }
  if (status === 429) {
    return { code: 429, message: "Rate limited", category: "rate_limit" };
  }
  if (status === 404) {
    return { code: 404, message: body, category: "not_found" };
  }
  return { code: status, message: body, category: "validation" };
}

Debugging Guide

Authentication Errors

Linktree API keys are passed via Authorization: Bearer header. Keys are scoped per account, not per profile. A 403 may indicate a plan-level restriction rather than a credentials issue -- verify the endpoint is available on your current plan tier before regenerating the key. Free-tier keys cannot access analytics or appearance customization endpoints.

Rate Limit Errors

The API enforces 100 requests/minute per key. Batch link creation using array endpoints when available. Analytics endpoints have stricter limits (30/min). Use the Retry-After header value and implement exponential backoff starting at 1 second.

Validation Errors

Link URLs must include the https:// or http:// scheme. Custom schemes (e.g., mailto:, tel:) are not supported via API. Titles are capped at 100 characters. Thumbnail URLs must resolve to valid image formats (PNG, JPG, GIF). Profile appearance updates fail silently if the theme ID does not exist -- validate theme availability first.

Error Handling

Quick Diagnostic

# Verify API connectivity and key validity
curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer $LINKTREE_API_KEY" \
  https://api.linktr.ee/v1/profile

Resources

• Linktree Developer Docs
• Linktree API Reference

Next Steps

See linktree-debug-bundle.