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

# Error Handling

> Learn how to handle errors with the WebLinq API

The WebLinq API uses conventional HTTP response codes to indicate the success or failure of an API request:

* `2xx` indicates success
* `4xx` indicates an error that failed given the information provided
* `5xx` indicates an error with our servers

## Error Response Formats

WebLinq uses two different error response formats depending on the type of error:

### Validation Errors (422 Unprocessable Entity)

When request validation fails, you'll receive a detailed error response with specific field-level issues:

```json Validation Error Format theme={null}
{
  "success": false,
  "error": {
    "issues": [
      {
        "code": "invalid_type",
        "path": ["url"],
        "message": "Expected string, received number"
      },
      {
        "code": "too_small",
        "path": ["waitTime"],
        "message": "Number must be greater than or equal to 0"
      }
    ],
    "name": "ZodError"
  }
}
```

### Other Errors (401, 404, 500, etc.)

For authentication, authorization, not found, and server errors, you'll receive a simpler format:

```json Simple Error Format theme={null}
{
  "success": false,
  "error": {
    "message": "Authentication required",
    "code": "authentication_required"
  }
}
```

## Common HTTP Status Codes

### 200 OK

Request succeeded. The response will contain the requested data.

### 401 Unauthorized

Authentication required. You need to provide a valid API key.

**Example Response:**

```json theme={null}
{
  "success": false,
  "error": {
    "message": "Authentication required",
    "code": "authentication_required"
  }
}
```

### 404 Not Found

The requested resource doesn't exist.

**Example Response:**

```json theme={null}
{
  "success": false,
  "error": {
    "message": "API key not found",
    "code": "not_found"
  }
}
```

### 422 Unprocessable Entity

Request validation failed. Check the `issues` array for specific field errors.

**Example Response:**

```json theme={null}
{
  "success": false,
  "error": {
    "issues": [
      {
        "code": "invalid_url",
        "path": ["url"],
        "message": "Must be a valid URL"
      }
    ],
    "name": "ZodError"
  }
}
```

### 429 Too Many Requests

Rate limit exceeded. Wait before making more requests.

**Example Response:**

```json theme={null}
{
  "success": false,
  "error": {
    "message": "Rate limit exceeded. Please try again later",
    "code": "rate_limit_exceeded"
  }
}
```

### 500 Internal Server Error

Something went wrong on our end. Try again later.

**Example Response:**

```json theme={null}
{
  "success": false,
  "error": {
    "message": "An unexpected error occurred",
    "code": "internal_server_error"
  }
}
```

## Error Handling Best Practices

### 1. Always Check the `success` Field

```javascript theme={null}
const response = await fetch('/api/web/screenshot', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer your-api-key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ url: 'https://example.com' }),
});

const data = await response.json();

if (!data.success) {
  // Handle error
  console.error('API Error:', data.error);
  return;
}

// Use successful data
console.log('Screenshot taken:', data.data);
```

### 2. Handle Validation Errors Specifically

```javascript theme={null}
if (response.status === 422) {
  // Validation error - check individual field issues
  data.error.issues.forEach((issue) => {
    console.error(`Field '${issue.path.join('.')}': ${issue.message}`);
  });
} else {
  // Other error - display general message
  console.error(`Error (${data.error.code}): ${data.error.message}`);
}
```

## Need Help?

If you encounter persistent errors, please contact our support team with:

* The HTTP status code
* The complete error response
* Your request payload (without sensitive data)
* The timestamp when the error occurred

<Card title="Get Support" icon="envelope" href="mailto:support@weblinq.dev">
  Contact our support team for assistance
</Card>