errors.mdx

title	Error Handling
description	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:

{
  "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:

{
  "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:

{
  "success": false,
  "error": {
    "message": "Authentication required",
    "code": "authentication_required"
  }
}

404 Not Found

The requested resource doesn't exist.

Example Response:

{
  "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:

{
  "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:

{
  "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:

{
  "success": false,
  "error": {
    "message": "An unexpected error occurred",
    "code": "internal_server_error"
  }
}

Error Handling Best Practices

1. Always Check the success Field

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

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

Contact our support team for assistance