​
Overview

When errors occur, Peekalink returns consistent responses designed to help you identify and fix issues quickly. Each error response includes:

  • status (number): The corresponding HTTP status code
  • error (string): A short identifier (e.g., LINK_INVALID_URL)
  • message (string): A brief explanation
  • details (optional): Additional context for debugging

A typical error response:

{
  "ok": false,
  "status": 400,
  "error": "LINK_INVALID_URL",
  "message": "Link has an invalid URL",
  "details": {}
}

​
Common Error Codes

Below is a non-exhaustive list of errors you might encounter.

  • LINK_INVALID_URL (400)
    The provided URL is malformed or unrecognized.
  • LINK_MAX_REDIRECTS (400)
    Exceeded our maximum redirect count.
  • LINK_REDIRECTS_TO_ITSELF (400)
    The URL loops back to itself.
  • LINK_IS_GONE (410)
    The server reported the resource as permanently gone.
  • LINK_CONTENT_ERROR (400)
    A parsing or metadata extraction issue occurred.
  • LINK_BLOCKED (403)
    This URL is blocked by our policy.
  • LINK_CONTENT_WAS_NOT_AS_EXPECTED (400)
    The content differs from what Peekalink anticipated.
  • LINK_TOOK_TOO_LONG (504)
    The link took too long to load.
  • LINK_SERVER_ERROR (500)
    The link’s server returned an unexpected 5xx error.
  • LINK_CONNECTION_ERROR (502)
    A network or DNS issue occurred when connecting to the link.
  • LINK_IS_NOT_SUPPORTED (400)
    The domain or file type is not supported by Peekalink.

​
Authentication & Rate Limits

  • NO_API_KEY (401)
    No API key provided.
  • INVALID_API_KEY (401)
    The API key is invalid or expired.
  • RATE_LIMIT_EXCEEDED (429)
    Exceeded your plan’s hourly or daily request quota.
  • BURST_LIMIT_EXCEEDED (503)
    Surpassed a short-term rate limit (per-minute bursts).
  • UNAUTHORIZED (401)
    General unauthorized access error.

​
Other Errors

  • NOT_FOUND (404)
    The requested resource wasn’t found in our system.
  • HEALTH_CHECK_ERROR (503)
    Internal health checks failed temporarily.
  • BAD_REQUEST (400)
    The request is malformed or missing required data.
  • PRISMA_<code> (400 or 500)
    Database-level error. In production, we mask details for security.

​
Handling Errors

  1. Check status: Determine if it’s a client error (4xx) or server error (5xx).
  2. Check error: Use this short code in your own logic (e.g., LINK_INVALID_URL vs. RATE_LIMIT_EXCEEDED).
  3. Check message: Provide a human-readable explanation in logs or UI.
  4. Check details: Additional info for debugging (e.g., how many redirects we followed).

​
Example Error Handling (Pseudocode)

try {
  const response = await fetchPeekalink(url);
  if (!response.ok) {
    console.error("Peekalink Error:", response.error, response.message);
    // Optionally, handle specific codes
    if (response.error === "LINK_INVALID_URL") {
      alert("Please provide a valid URL.");
    }
  }
} catch (err) {
  // Network issues / unexpected errors
  console.error("Unhandled error:", err);
}

​
Final Notes

  • Stay Within Your Plan Limits: Keep an eye on rate limits to avoid RATE_LIMIT_EXCEEDED.
  • Validate URLs Upfront: If you know a URL is invalid, handle it before calling Peekalink.
  • Upgrade for High Volumes: If you’re frequently hitting 429 or 503 errors, consider a higher plan.
  • Need Help? Join our Discord or check out our Support page for guidance.

By understanding Peekalink’s error codes, you can quickly pinpoint issues and deliver a seamless experience for your users. If you have questions or suggestions, feel free to reach out—our goal is to make link previews as smooth and transparent as possible.