> ## Documentation Index
> Fetch the complete documentation index at: https://docs.peekalink.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Handling

> Learn how Peekalink handles errors and the set of error codes returned by our service.

## 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:

```json theme={null}
{
  "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 & Metadata

* **`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)

```js theme={null}
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](https://www.peekalink.io/discord) or check out our [Support](https://docs.peekalink.io/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.