OpenParable
Skip to content
← Back to skills

Linktree Common Errors

Testing & Quality
linktree-common-errors

Linktree Common Errors is an Agent Skill for testing & quality published in the jeremylongshore/claude-code-plugins-plus-skills repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Diagnose and fix Linktree common errors. Trigger: "linktree error", "fix linktree", "debug linktree".

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/jeremylongshore/claude-code-plugins-plus-skills/blob/HEAD/plugins/saas-packs/linktree-pack/skills/linktree-common-errors/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/linktree-common-errors, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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

CodeMessageCauseFix
400Invalid URL formatLink URL missing scheme or malformedEnsure URLs include https:// prefix and pass URL validation
401Authentication failedAPI key invalid or expiredRegenerate key at linktr.ee developer portal
403Plan feature restrictedEndpoint requires Pro/Premium planUpgrade plan or use alternative endpoint for free tier
404Profile not foundUsername does not exist or is deactivatedVerify username spelling; check profile is active
404Link not foundLink ID deleted or belongs to another profileList links first to confirm valid IDs
409Duplicate linkSame URL already exists on profileCheck existing links before adding; update instead of create
422Validation errorTitle too long or thumbnail URL invalidTitle max 100 chars; thumbnail must be valid image URL
429Rate limitedExceeded 100 requests/minuteImplement exponential backoff; check Retry-After header

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

ScenarioPatternRecovery
Link validation failsURL missing schemePrepend https:// and retry
Analytics returns emptyData not yet availableAnalytics lag 15-30 min; retry after delay
Profile lookup failsUsername typo or deactivatedSearch by email if available; confirm active status
Duplicate link on createSame URL already on profileFetch existing links, update instead of create
Bulk link import partial failureSome URLs invalidParse error array, fix URLs, retry failed items

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

Next Steps

See linktree-debug-bundle.